WakaTime Authentication: API Keys & OAuth 2.0 (2026)

Authentication overview

WakaTime provides two primary methods for authenticating requests to its API: API keys and OAuth 2.0. The choice of method depends on the nature of the integration. API keys, often referred to as personal access tokens, are suitable for direct user access, personal scripts, and server-side applications where a single user's data is accessed. OAuth 2.0 is designed for third-party applications that need to access WakaTime data on behalf of users without requiring them to share their direct credentials, providing a secure and standardized delegation mechanism. Both methods ensure that only authorized entities can retrieve coding activity, summaries, and user statistics from the WakaTime platform.

WakaTime's API is RESTful, returning JSON-formatted data, and its integration process is designed for developers building custom tools or analyzing their own coding habits. The API's architecture expects authentication credentials in the request headers, following standard practices for secure API access.

Supported authentication methods

WakaTime supports the following authentication methods for accessing its API:

API Key (Personal Access Token)

• Description: A unique, long-lived string generated by a user within their WakaTime account. It acts as a secret key that grants access to the user's data. API keys are typically passed in the Authorization header using the Bearer scheme or as a query parameter.
• When to use: Ideal for personal scripts, command-line tools, internal server-side applications, and WakaTime's official IDE plugins where the application directly accesses one user's data. It provides straightforward access for single-user scenarios.
• Security level: Moderate. The security of an API key relies entirely on its secrecy. If compromised, it grants full access to the associated user's WakaTime data. Rotation and secure storage are critical.

OAuth 2.0

• Description: An industry-standard protocol for authorization that allows a third-party application to obtain limited access to a user's WakaTime account without exposing the user's credentials. WakaTime implements the Authorization Code grant type, which is recommended for web applications. The flow involves redirecting the user to WakaTime for authorization, receiving an authorization code, and then exchanging that code for an access token and refresh token.
• When to use: Recommended for public-facing web applications, mobile applications, or any third-party service that needs to access WakaTime data on behalf of multiple users. It provides a secure way to manage delegated access and user consent.
• Security level: High. OAuth 2.0 minimizes the risk of credential exposure by providing temporary, scoped access tokens. Refresh tokens allow for continuous access without re-authentication, and the authorization code flow ensures tokens are not directly exposed in the user agent.

Here's a comparison of the two methods:

Getting your credentials

For API Keys:

1. Navigate to the WakaTime Account Settings page.
2. Locate the API Key section.
3. Your API key will be displayed. Copy this key and store it securely. Treat it like a password.

WakaTime also provides official IDE plugins that typically handle API key management internally after initial setup, abstracting the direct token handling from the user.

For OAuth 2.0:

To use OAuth 2.0, you must register your application with WakaTime to obtain a Client ID and Client Secret. This process typically involves:

1. Logging into your WakaTime account.
2. Accessing the Developer Apps section or a similar developer console.
3. Registering a new application, providing details such as application name, description, and crucially, one or more Redirect URIs. These URIs are where WakaTime will redirect the user after they grant or deny authorization.
4. Upon registration, WakaTime will provide a Client ID and a Client Secret. The Client ID is public, but the Client Secret must be kept confidential and never exposed in client-side code.

The OAuth 2.0 flow will then involve:

1. Directing users to WakaTime's authorization endpoint with your Client ID and desired scope.
2. WakaTime authenticates the user and prompts for authorization.
3. Upon approval, WakaTime redirects the user back to your specified Redirect URI with an authorization code.
4. Your application exchanges this authorization code for an access token and refresh token using your Client ID and Client Secret from your server-side application.
5. The access token is then used to make API calls on behalf of the user.

Authenticated request example

This example demonstrates how to make an authenticated request using an API key to fetch a user's daily summary. Replace YOUR_API_KEY with your actual WakaTime API key.

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://wakatime.com/api/v1/users/current/summaries?start=2024-01-01&end=2024-01-01"

For OAuth 2.0, after obtaining an access token, the request structure is similar:

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     "https://wakatime.com/api/v1/users/current/summaries?start=2024-01-01&end=2024-01-01"

In both cases, the Bearer token is placed in the Authorization header, a standard practice for HTTP Bearer authentication.

Security best practices

Securing your WakaTime API integrations is crucial to protect user data and maintain service integrity. Adhere to these best practices:

API Key Security:

• Keep API Keys Confidential: Never hardcode API keys directly into public repositories, client-side code, or commit them to version control. Use environment variables, secret management services, or secure configuration files.
• Server-Side Usage: Ideally, use API keys only on your server-side applications where they can be properly secured. Avoid exposing them in client-side JavaScript or mobile applications.
• Regular Rotation: Periodically rotate your API keys. If an API key is ever compromised, revoke it immediately from your WakaTime account settings and generate a new one.
• Principle of Least Privilege: While WakaTime API keys generally grant broad access to a user's data, ensure your application only performs actions necessary for its functionality.
• HTTPS Only: Always use HTTPS for all API communications to encrypt data in transit and prevent man-in-the-middle attacks. WakaTime's API endpoints enforce HTTPS.

OAuth 2.0 Security:

• Protect Client Secret: The OAuth Client Secret must be treated with the same confidentiality as an API key. Store it securely on your server and never expose it in client-side code.
• Validate Redirect URIs: Configure strict and specific Redirect URIs for your OAuth application. This prevents attackers from redirecting authorization codes to malicious endpoints.
• Use State Parameter: Implement the state parameter during the authorization request to prevent Cross-Site Request Forgery (CSRF) attacks. The state parameter should be a unique, unguessable value generated by your application and verified upon callback.
• Handle Tokens Securely: Store access tokens and refresh tokens securely. Access tokens are short-lived; refresh tokens allow obtaining new access tokens without user re-authentication. Encrypt these tokens at rest and restrict access.
• Token Revocation: Provide a mechanism for users to revoke access tokens from your application or from their WakaTime account settings.
• Scope Management: Request only the necessary scopes (permissions) from the user. This limits the data your application can access and improves user trust.

General Security Practices:

• Input Validation: Sanitize and validate all input to your application to prevent injection attacks and other vulnerabilities.
• Error Handling: Implement robust error handling that avoids leaking sensitive information in error messages or logs.
• Logging and Monitoring: Log API access and authentication attempts to identify and respond to suspicious activity.
• Regular Audits: Periodically review your application's security posture and adhere to general web security best practices.
• Educate Users: If your application interacts with user credentials, provide clear instructions on how to keep their WakaTime account secure.