Authentication

The Trakt API uses OAuth 2.0 for user authentication. Some endpoints are "public" and only require your API key, while others require an authenticated user access token. A few endpoints can also return more personalized results when OAuth is provided, even if authentication is optional.

Every app should send the required Trakt API headers, including your trakt-api-key. For endpoints that require or support OAuth, also send the user access token as a Bearer token: Authorization: Bearer <access_token>

📝 The redirect_uri is case-sensitive. It must exactly match the URI configured in your Trakt application in both the authorization request and token exchange.

Trakt supports two OAuth flows:

1. Authorization Code Flow - Best for apps that can open a browser and receive a redirect callback.
2. Device Code Flow - Best for TVs, media centers, CLI tools, and other devices with limited input.

Learn more: Authentication

Check each endpoint’s documentation to see whether OAuth is required, optional, or not needed.

Refreshing an Access Token

Access tokens are valid for 7 days. Use the refresh_token returned during authorization with the POST /oauth/token endpoint to obtain a new access token without asking the user to authorize your app again.

⚠️ Refresh tokens are single-use. Every successful refresh returns a new access_token and refresh_token. The refresh token used in the request is immediately invalidated, so always replace your stored tokens with the values from the response.

If the token exchange cannot be completed, the API returns a 400 response with an OAuth error body:

{
  "error": "invalid_grant",
  "error_description": "session not found"
}

Make sure your HTTP client preserves response bodies for non-successful requests so this information is not discarded.

🗒️ Legacy Refresh Tokens

Refresh tokens issued before the recent authentication migration can no longer be exchanged. If an affected user receives invalid_grant with session not found, ask them to authorize the application again once. Tokens issued afterward refresh normally.