TVDB Authentication: Methods, Setup & Security (2026)

Authentication overview

The TVDB API, a resource for TV series, movie, and anime metadata, employs an authentication system designed to secure access and manage usage. This system is primarily based on the OAuth 2.0 framework, specifically utilizing a client credentials grant-like flow for applications to obtain access tokens. Users authenticate their applications by combining an API Key, a User Key (for V3 API and some legacy V4 operations), and an Account ID to receive a session token. This token, a JSON Web Token (JWT), then authorizes subsequent API calls for a limited duration.

Adherence to the authentication protocols ensures that API requests are accounted for against the user's plan limits and that data access is restricted to authorized applications. All communication with the TVDB API must occur over HTTPS to protect credentials and data in transit. The V4 API represents an evolution from previous versions, introducing a more standardized approach to token-based authentication, moving away from older, simpler API key-only methods.

Understanding the proper setup and usage of the authentication flow is critical for developers to integrate TVDB data into their applications reliably and securely, avoiding unauthorized access or service interruptions due to invalid credentials or expired tokens.

Supported authentication methods

TVDB primarily supports an OAuth 2.0-based mechanism for authenticating API requests. This method involves exchanging a set of user-specific credentials for a temporary access token.

1. API Key and User Key/Account ID for Token Acquisition: This is the core authentication flow for the V4 API. Developers use their unique API Key (sometimes referred to as Client ID), along with a User Key (for older V3 compatibility or specific V4 endpoints) and their Account ID, to request a session token from the /login endpoint. The response includes a JWT access token that must be included in the Authorization header of all subsequent API calls.
2. Bearer Token (JWT): Once obtained, the JWT access token is used as a Bearer token. This is the standard mechanism for authorizing requests to protected resources in HTTP. The token proves the application has been authenticated and is authorized to access the requested data for its lifespan.

The following table summarizes the primary authentication method:

Getting your credentials

To authenticate with the TVDB API, you need to obtain specific credentials from your TVDB account. These credentials typically include an API Key, a User Key (if applicable for your integration), and your Account ID.

1. Create a TVDB Account: If you don't already have one, register for a free account on the TVDB website.
2. Access the API Key Page: After logging in, navigate to your account dashboard or a dedicated API section. The specific path may vary, but you will typically find a link related to 'API Key' or 'Developer Settings'. Refer to the TVDB API Key documentation for the exact location.
3. Generate an API Key: Follow the instructions on the page to generate your unique API Key. This key is crucial for identifying your application to the TVDB API.
4. Locate Your User Key (if needed): For some integrations, particularly those bridging V3 and V4 API functionalities, a 'User Key' might be required. This is often found alongside your API Key or in your profile settings. For most V4-only integrations, the API Key and Account ID should suffice.
5. Note Your Account ID: Your unique TVDB Account ID is also a necessary component for the authentication process, especially when constructing the login payload. This is usually visible in your account profile.

Store these credentials securely. Never hardcode them directly into client-side code, and avoid exposing them in public repositories.

Authenticated request example

The following example demonstrates how to obtain an access token and then use it to make an authenticated request to the TVDB API V4, using a hypothetical API Key, User Key, and Account ID.

Step 1: Obtain a session token

First, make a POST request to the /login endpoint with your credentials. This example uses curl, but any HTTP client can be used.

curl -X POST \n  https://api4.thetvdb.com/v4/login \n  -H 'Content-Type: application/json' \n  -d '{ \n    "apikey": "YOUR_API_KEY", \n    "accountid": "YOUR_ACCOUNT_ID", \n    "userkey": "YOUR_USER_KEY" \n  }'

A successful response will contain a JSON object with a token field:

{ \n  "data": { \n    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2..." \n  } \n}

Extract the token value for subsequent requests.

Step 2: Make an authenticated API call

Once you have the token, include it in the Authorization header as a Bearer token for all protected endpoints. This example fetches details for a TV series.

export TVDB_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2..." \ncurl -X GET \n  https://api4.thetvdb.com/v4/series/71663 \n  -H 'Authorization: Bearer '$TVDB_TOKEN \n  -H 'Accept: application/json'

Replace YOUR_API_KEY, YOUR_ACCOUNT_ID, and YOUR_USER_KEY with your actual credentials. The series ID 71663 is an example; use a valid ID for your query. The TVDB V4 API Reference provides detailed information on available endpoints and required parameters.

Security best practices

Securing your integration with the TVDB API is essential to protect your credentials and maintain the integrity of your application. Adhering to these best practices can mitigate common security risks:

1. Keep Credentials Confidential: Treat your API Key, User Key, and Account ID as sensitive information. Never commit them directly into your codebase, especially if it's publicly accessible (e.g., GitHub). Use environment variables, secure configuration files, or secret management services (e.g., AWS Secrets Manager, Azure Key Vault, Google Secret Manager) to store and retrieve them.
2. Use HTTPS Exclusively: Always ensure that all communication with the TVDB API occurs over HTTPS. The API explicitly requires this, but it's a fundamental security practice to prevent man-in-the-middle attacks where sensitive data, including your authentication token, could be intercepted.
3. Manage Access Tokens Securely: Once you receive an access token, store it in a temporary, secure manner. Avoid storing it in client-side storage (like local storage) if your application is browser-based, as it can be vulnerable to XSS attacks. For server-side applications, keep tokens in memory for their active duration and invalidate them securely upon expiry or logout.
4. Refresh Tokens Appropriately: Access tokens have a limited lifespan. Implement a robust mechanism to detect expired tokens and automatically request a new one using your stored credentials. Do not hardcode tokens or rely on excessively long-lived tokens, as this increases the window for potential compromise.
5. Implement Rate Limiting and Error Handling: While not strictly an authentication best practice, robust error handling for authentication failures (e.g., 401 Unauthorized) and adherence to TVDB's rate limits are crucial. Repeated failed authentication attempts can trigger IP bans or other security measures. Gracefully handle token expiration and invalid token errors.
6. Principle of Least Privilege: Design your application to request and utilize only the necessary permissions or access levels. While TVDB's current OAuth flow is mainly for general API access, always consider this principle when integrating with any API.
7. Monitor API Usage: Regularly review your API usage logs, if available, to detect any suspicious activity or unexpected request patterns that might indicate a compromised key or unauthorized access.
8. Regularly Rotate Credentials: Periodically rotate your API Key and User Key, especially if you have a team of developers. This minimizes the risk associated with a single key being compromised over a long period. If a key is suspected to be compromised, revoke it immediately and generate a new one.