Simkl Authentication: API Key and OAuth 2.0 (2026)

Authentication overview

Simkl provides an API for developers to integrate with its media tracking and synchronization services. Access to the Simkl API requires authentication to ensure that requests are authorized and associated with a valid account. The choice of authentication method depends on the application's nature and the level of access required to user data. Simkl primarily offers two authentication mechanisms: API keys for server-side applications or direct access, and OAuth 2.0 for client-side applications that need to interact with user-specific data after obtaining user consent.

API access through Simkl is generally available to users on a paid VIP tier, starting from $0.99 per month, which enables advanced features and API functionality. This ensures that API usage is tied to a subscribed account, managing resource allocation and preventing unauthorized access. The API itself is RESTful, returning data in JSON format, consistent with modern web service architectures.

Understanding the distinctions between API key and OAuth 2.0 authentication is crucial for designing secure and efficient integrations. API keys are suitable for services where the application itself owns the data or has administrative privileges. In contrast, OAuth 2.0 is designed for scenarios where an application needs to access a user's data on their behalf without ever handling their primary login credentials. This delegated authorization flow enhances security by limiting the scope of access and providing users with control over their data permissions.

Supported authentication methods

Simkl supports two primary methods for authenticating API requests:

• API Keys: A simple token-based authentication method suitable for server-to-server communication or applications where the API key can be securely stored. API keys are typically associated with your Simkl account and grant broad access to your application's data or the capabilities enabled by your VIP subscription.
• OAuth 2.0: An industry-standard protocol for authorization that allows third-party applications to obtain limited access to a user's account without exposing user credentials. This method is ideal for client-side applications (e.g., mobile apps, web applications) that need to access user-specific data (like watch history or watchlists) with the user's explicit consent. OAuth 2.0 involves a flow where the user grants permission to your application, and in return, your application receives an access token to make authenticated requests on behalf of that user. For detailed information on the OAuth 2.0 authorization framework, refer to the OAuth 2.0 specification overview.

Authentication methods comparison

Getting your credentials

To access the Simkl API, you must first obtain the necessary credentials. This process typically involves registering your application and generating API keys or OAuth 2.0 client credentials through the Simkl website.

For API Keys:

1. Sign up for a Simkl VIP account: API access is a feature for VIP members. Ensure you have an active Simkl VIP subscription.
2. Navigate to the API section: Log in to your Simkl account and locate the developer or API section, typically found in your account settings.
3. Generate an API Key: Follow the instructions to create a new application or generate a new API key. Simkl's documentation provides specific guidance on this process on their Simkl developer portal. This key is a unique string that identifies your application.
4. Record your API Key: Once generated, store your API key securely. It is crucial not to expose this key in client-side code or public repositories.

For OAuth 2.0 Client Credentials:

1. Sign up for a Simkl VIP account: Similar to API keys, OAuth 2.0 access also requires a Simkl VIP membership.
2. Register your application: Access the developer settings within your Simkl account. You will need to register your application, providing details such as your application's name, description, and importantly, redirect URIs. Redirect URIs are where Simkl will send the user back after they authorize your application.
3. Obtain Client ID and Client Secret: Upon successful registration, Simkl will provide you with a Client ID and Client Secret. The Client ID is public and identifies your application. The Client Secret is a confidential key used to authenticate your application when requesting access tokens. Treat your Client Secret with the same level of security as an API key.
4. Understand the OAuth Flow: Implement the OAuth 2.0 authorization code flow for web applications or other suitable flows for different application types. This involves directing the user to Simkl's authorization page, handling the callback with an authorization code, and exchanging that code for an access token and refresh token. For a comprehensive understanding of OAuth 2.0 flows, refer to the IETF RFC 6749.

Authenticated request example

Below are examples demonstrating how to make authenticated requests using both API keys and OAuth 2.0 with the Simkl API. These examples use cURL, a common command-line tool for making HTTP requests, as specified in the Simkl developer experience notes.

Using an API Key

When using an API key, you typically include it as a query parameter or an HTTP header, depending on the API's design. Simkl's API documentation indicates that the API key is often passed as a query parameter named client_id.

curl "https://api.simkl.com/movies/now_playing?client_id=YOUR_API_KEY" \
     -H "Content-Type: application/json"

Replace YOUR_API_KEY with the actual API key you generated from your Simkl account. This example fetches currently playing movies using the provided API key for authentication.

Using OAuth 2.0 Access Token

For OAuth 2.0, after a user authorizes your application and you exchange the authorization code for an access token, you typically include the access token in the Authorization header of your HTTP requests, using the Bearer scheme.

curl "https://api.simkl.com/sync/history?client_id=YOUR_CLIENT_ID" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

In this example, YOUR_CLIENT_ID refers to your application's Client ID obtained during registration, and YOUR_ACCESS_TOKEN is the token acquired through the OAuth 2.0 flow. This request, for instance, could fetch the authenticated user's watch history. The client_id parameter might still be required by Simkl's API for rate limiting or application identification, even when using an access token.

Security best practices

Employing robust security practices is essential when integrating with any API, especially when handling sensitive user data or proprietary access credentials. Following these best practices will help protect your application and user information when using Simkl's authentication methods.

API Key Security:

• Do not embed keys directly in code: Avoid hardcoding API keys in your application's source code, especially in client-side code or public repositories.
• Use environment variables: For server-side applications, store API keys in environment variables or configuration files that are not committed to version control.
• Restrict API key privileges: If Simkl offers options to create API keys with specific scopes or permissions, generate keys with the minimum necessary privileges for your application's functionality.
• Secure storage: If keys must be stored, use secure storage mechanisms, such as encrypted vaults or cloud-based secret management services provided by platforms like AWS Secrets Manager or Google Cloud Secret Manager.
• Regular rotation: Periodically rotate your API keys. This practice minimizes the risk profile if a key is compromised.
• IP Whitelisting: If Simkl supports IP whitelisting for API keys, configure it to allow requests only from your application's known server IP addresses.

OAuth 2.0 Security:

• Protect your Client Secret: Treat your OAuth 2.0 Client Secret with the same care as an API key. Never expose it in client-side code.
• Validate Redirect URIs: Ensure that all configured redirect URIs are secured (HTTPS) and strictly controlled. Only register URIs that your application legitimately uses.
• Use HTTPS exclusively: All communication between your application, Simkl, and the user's browser during the OAuth flow must occur over HTTPS to prevent eavesdropping and man-in-the-middle attacks.
• Securely store Access and Refresh Tokens: Access tokens are short-lived. Refresh tokens, which are used to obtain new access tokens without re-authenticating the user, should be stored securely on the server-side, ideally encrypted, and associated with the user account.
• Implement State Parameter: Use the state parameter in your OAuth authorization requests to prevent Cross-Site Request Forgery (CSRF) attacks. This parameter should be a unique, unguessable value generated by your application for each authorization request.
• Handle scope carefully: Request only the necessary scopes (permissions) from the user. Over-requesting permissions can deter users and increase your application's attack surface.
• Error Handling: Implement robust error handling for failed token exchanges or authorization attempts to prevent potential security vulnerabilities or service interruptions.