Authentication

SubX API uses API keys for authentication. All API requests (except /api/health) require authentication.

Creating an API Key

To use the SubX API, you'll need to create an API key from the web interface.

Steps to Create an API Key

1. Sign In to the SubX web application
2. Navigate to Profile or API Keys section in your account settings
3. Click "Create New API Key"
4. Give your API key a descriptive name (e.g., "My App Production", "Testing")
5. Optionally set an expiration date for added security
6. Click "Generate Key"

Save Your API Key

The API key will only be displayed once when you create it. Make sure to copy it to a secure location immediately. If you lose it, you'll need to generate a new one.

Using Your API Key

Include your API key in the Authorization header of every protected API request:

Authorization: Bearer {YOUR_API_KEY_HERE}

For example:

Authorization: Bearer 1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s0t

Example Request

cURLPythonJavaScript

curl -X GET "https://subx-api.duckdns.org/api/subtitles/search?title=Dexter&limit=10" \
  -H "Authorization: Bearer {YOUR_API_KEY_HERE}"

import requests

headers = {
    "Authorization": "Bearer {YOUR_API_KEY_HERE}"
}

response = requests.get(
    "https://subx-api.duckdns.org/api/subtitles/search",
    headers=headers,
    params={"title": "Dexter", "limit": 10}
)
print(response.json())

const response = await fetch(
  'https://subx-api.duckdns.org/api/subtitles/search?title=Dexter&limit=10',
  {
    headers: {
      'Authorization': 'Bearer {YOUR_API_KEY_HERE}'
    }
  }
);

const data = await response.json();
console.log(data);

Managing Your API Keys

Viewing Your Keys

You can view all your active API keys in the web interface:

1. Go to Profile → API Keys
2. You'll see a list of all your keys with:
3. Key name
4. Creation date
5. Last used date
6. Expiration date (if set)
7. Usage statistics

Revoking a Key

If you need to revoke an API key:

1. Navigate to Profile → API Keys
2. Find the key you want to revoke
3. Click "Revoke" or the trash icon
4. Confirm the action

Caution

Revoking an API key is permanent and immediate. Any applications using that key will stop working immediately.

Security Best Practices

Do's ✅

• Store keys securely - Use environment variables or secret management systems
• Use different keys for different applications or environments
• Set expiration dates for keys when possible
• Rotate keys periodically for enhanced security
• Monitor usage to detect unusual activity

Don'ts ❌

• Don't commit keys to version control (Git, etc.)
• Don't share keys publicly or via email
• Don't use the same key across multiple unrelated applications
• Don't hardcode keys in your source code

Environment Variables Example

BashPythonJavaScript

# .env file
SUBX_API_KEY={YOUR_API_KEY_HERE}

import os
from dotenv import load_dotenv

# Load environment variables from .env file
load_dotenv()

api_key = os.getenv('SUBX_API_KEY')
headers = {"Authorization": f"Bearer {api_key}"}

// Using dotenv package
require('dotenv').config();

const apiKey = process.env.SUBX_API_KEY;
const headers = {
  'Authorization': `Bearer ${apiKey}`
};

Authentication Errors

401 Unauthorized

This error occurs when:

• No API key is provided
• The API key is invalid or malformed
• The API key has been revoked

Response:

{
  "detail": "Invalid authentication credentials"
}

Solution: Check that you're sending the correct API key in the Authorization header.

403 Forbidden

This error occurs when:

• The API key is valid but doesn't have permission for the requested resource
• The API key has expired

Response:

{
  "detail": "Forbidden"
}

Solution: Verify that your API key hasn't expired and has the necessary permissions.

Rate Limiting

API keys are subject to rate limiting to ensure fair usage. See the Rate Limits Guide for details.

Next Steps

Now that you understand authentication, let's make your first API request! Continue to the Quickstart Guide.