Todoist Authentication: API Tokens & OAuth 2.0 (2026)

Authentication overview

Todoist provides authentication mechanisms for its API to allow developers to build integrations and applications that interact with user task data. The choice of authentication method depends on the nature of the integration: whether it's a personal script accessing a single user's data or a public application designed for multiple users. Secure authentication is critical to protect user data and maintain the integrity of task management workflows.

The Todoist API supports two primary methods for authentication: API tokens (also known as personal access tokens) and OAuth 2.0. API tokens are suitable for private, script-based integrations where a single user grants direct access. OAuth 2.0 is the recommended standard for third-party applications that need to access user data on their behalf without requiring the user to share their Todoist credentials directly. This approach aligns with modern security practices for delegated authorization, as outlined by the OAuth 2.0 specification.

Supported authentication methods

Todoist offers distinct authentication methods tailored to different integration scenarios:

API Tokens (Personal Access Tokens)

API tokens are long-lived strings that grant direct access to a user's Todoist account. They are ideal for:

• Personal scripts or command-line tools.
• Internal integrations within a small team where the token can be securely managed.
• Automations that operate on a single user's data.

When using an API token, the token itself acts as the authentication credential. It should be treated with the same level of security as a password because it provides full access to the associated Todoist account's data, subject to the API's permissions. Users can generate and revoke these tokens from their Todoist settings, as detailed in the Todoist API token guide.

OAuth 2.0

OAuth 2.0 is an industry-standard protocol for authorization that enables third-party applications to obtain limited access to a user's data without exposing their password. It is the preferred method for:

• Public-facing applications that serve multiple users.
• Integrations requiring explicit user consent for specific data access (scopes).
• Applications that need temporary or revocable access.

Todoist's OAuth 2.0 implementation typically follows the Authorization Code Grant flow. This flow involves redirecting the user to Todoist's authorization server, where they log in and grant permission to the application. Upon successful authorization, Todoist redirects the user back to the application with an authorization code, which the application then exchanges for an access token and a refresh token. The access token is used to make API calls, while the refresh token can be used to obtain new access tokens when the current one expires, without requiring the user to re-authorize.

The following table summarizes the authentication methods:

Getting your credentials

For API Tokens:

1. Log in to your Todoist account on the web.
2. Navigate to Settings > Integrations.
3. Locate the API token section.
4. Your personal API token will be displayed there. Copy it securely.

Refer to the official Todoist API token documentation for the most up-to-date instructions.

For OAuth 2.0:

To use OAuth 2.0, you must first register your application with Todoist to obtain a Client ID and Client Secret:

1. Visit the Todoist Developer Console.
2. Click 'Create a new app'.
3. Provide your application's name, description, and at least one Redirect URI (where Todoist will send the authorization code after user consent).
4. After registration, Todoist will provide you with a Client ID and a Client Secret.

These credentials (Client ID and Client Secret) are unique to your application and identify it to Todoist's authorization server. The Client Secret, in particular, must be kept confidential, as it is used to authenticate your application when exchanging the authorization code for an access token. The Redirect URI(s) must exactly match those registered in your developer console for security reasons, preventing malicious redirection. Detailed steps are available in the Todoist API OAuth guide.

Authenticated request example

Using an API Token (Python example)

When using an API token, it is typically passed in the Authorization header with the Bearer scheme.

import requests
import os

# It's recommended to store your API token securely, e.g., in an environment variable
TODOIST_API_TOKEN = os.environ.get("TODOIST_API_TOKEN")

if not TODOIST_API_TOKEN:
    raise ValueError("TODOIST_API_TOKEN environment variable not set.")

headers = {
    "Authorization": f"Bearer {TODOIST_API_TOKEN}",
    "Content-Type": "application/json"
}

# Example: Fetching active tasks
response = requests.get("https://api.todoist.com/rest/v2/tasks", headers=headers)

if response.status_code == 200:
    tasks = response.json()
    for task in tasks:
        print(f"Task ID: {task['id']}, Content: {task['content']}")
else:
    print(f"Error fetching tasks: {response.status_code} - {response.text}")

Using an OAuth 2.0 Access Token (Conceptual example after obtaining token)

After completing the OAuth 2.0 flow and obtaining an access token, API requests are made similarly to API token requests, using the access token in the Authorization header.

GET /rest/v2/tasks HTTP/1.1
Host: api.todoist.com
Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN
Content-Type: application/json

The process of obtaining the OAuth 2.0 access token involves several steps (authorization request, user consent, callback, token exchange) which are typically handled by an OAuth 2.0 client library in your chosen programming language. The RFC 6749 provides the full specification for OAuth 2.0.

Security best practices

Adhering to security best practices is essential when integrating with the Todoist API to protect user data and maintain application integrity:

• Protect API Tokens and Client Secrets: Never hardcode API tokens or OAuth Client Secrets directly into your source code. Store them in environment variables, secure configuration files, or a dedicated secret management service (e.g., AWS Secrets Manager, Google Secret Manager, Azure Key Vault).
• Use OAuth 2.0 for Public Applications: For any application that will be used by multiple Todoist users, always implement OAuth 2.0. This prevents users from having to share their sensitive API tokens or passwords with your application.
• Limit Scopes (OAuth 2.0): Request only the minimum necessary permissions (scopes) from the user. For example, if your application only needs to read tasks, do not request write access. This limits the potential impact of a security breach.
• Secure Redirect URIs (OAuth 2.0): Ensure that your registered Redirect URIs are specific and use HTTPS. Avoid using wildcard Redirect URIs in production environments.
• Implement Token Refresh Securely (OAuth 2.0): If using refresh tokens, store them securely and handle their usage carefully. Revoke refresh tokens if any suspicious activity is detected.
• Regularly Rotate Credentials: While Todoist API tokens are persistent, it's a good practice to regenerate and update them periodically, especially in automated systems. For OAuth, ensure your application handles access token expiry and refresh token usage correctly.
• Error Handling and Logging: Implement robust error handling for authentication failures. Log authentication attempts and failures (without logging sensitive credentials) to monitor for potential attacks.
• HTTPS Everywhere: Always use HTTPS for all communication with the Todoist API and for your application's endpoints that handle sensitive information. This encrypts data in transit, protecting against eavesdropping and tampering.
• Revoke Compromised Credentials: If you suspect an API token or OAuth access token has been compromised, immediately revoke it through your Todoist settings or your application's OAuth management interface.
• Stay Updated: Keep your application's dependencies and libraries up to date to benefit from the latest security patches.