Authentication

Authenticate API requests using JWT tokens or API keys

Dispatcharr supports two authentication methods for API access: JWT (JSON Web Token) authentication and API key authentication. Both methods provide secure, stateless authentication for programmatic access.

Authentication Methods

JWT Token Authentication (Recommended)

JWT tokens are short-lived bearer tokens ideal for user sessions and frontend applications. Tokens expire after a configured period and can be refreshed using a refresh token.

API Key Authentication

API keys are long-lived credentials ideal for scripts, automations, and third-party integrations. Each user can generate a personal API key that authenticates requests without exposing account credentials.

API keys were added in version 0.20.0. Users can generate and revoke their own keys from the profile page. Admin users can manage keys for any user.

JWT Token Authentication

Obtaining a Token

Request a JWT token pair (access + refresh) using your username and password:

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your_username",
    "password": "your_password"
  }' \
  http://your-server:8000/api/accounts/token/

Response

{
  "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Using the Access Token

Include the access token in the Authorization header with the Bearer prefix:

cURL

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  http://your-server:8000/api/channels/

Refreshing Tokens

Access tokens expire after a configured period. Use the refresh token to obtain a new access token:

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}' \
  http://your-server:8000/api/accounts/token/refresh/

Response

{
  "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Refresh tokens also expire (typically after a longer period). When a refresh token expires, users must re-authenticate with username and password.

Alternative Login Endpoint

Dispatcharr also provides a custom login endpoint at /api/accounts/auth/login/ that returns the same token pair:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your_username",
    "password": "your_password"
  }' \
  http://your-server:8000/api/accounts/auth/login/

API Key Authentication

API keys provide a simpler authentication method for scripts and automations without the need to handle token expiration.

Generating an API Key

Users can generate their personal API key from the profile page in the Dispatcharr UI. Admin users can generate keys for any user.

Each user can have only one active API key. Generating a new key automatically revokes the previous one.

Using API Keys

API keys can be provided in two ways:

Method 1: Authorization Header (Recommended)

Use the Authorization header with the ApiKey prefix:

cURL

curl -H "Authorization: ApiKey your_api_key_here" \
  http://your-server:8000/api/channels/

Method 2: X-API-Key Header

Alternatively, use the X-API-Key header:

cURL

curl -H "X-API-Key: your_api_key_here" \
  http://your-server:8000/api/channels/

Revoking API Keys

API keys can be revoked from the user profile page in the Dispatcharr UI. Revocation is immediate—requests using revoked keys will be rejected.

API Key Management (Admin)

Admin users can manage API keys for all users via the accounts API:

# List all API keys (admin only)
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  http://your-server:8000/api/accounts/api-keys/

# Generate a key for a user (admin only)
curl -X POST \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user": 5}' \
  http://your-server:8000/api/accounts/api-keys/

# Revoke a specific key (admin only)
curl -X DELETE \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  http://your-server:8000/api/accounts/api-keys/123/

Authentication Errors

401 Unauthorized

Returned when authentication credentials are missing or invalid:

{
  "detail": "Authentication credentials were not provided."
}

Or:

{
  "detail": "Invalid token."
}

Or:

{
  "detail": "Invalid API key."
}

403 Forbidden

Returned when authenticated but lacking required permissions:

{
  "detail": "You do not have permission to perform this action."
}

Testing Authentication in Swagger UI

The interactive Swagger UI at /api/swagger/ supports both authentication methods:

Using JWT Tokens

1. Click the Authorize button (lock icon) at the top right
2. In the “Bearer” section, enter your JWT token (without the “Bearer ” prefix)
3. Click Authorize
4. All subsequent requests will include the token automatically

Using API Keys

1. Click the Authorize button (lock icon) at the top right
2. In the “ApiKey” section, enter your API key
3. Click Authorize
4. All subsequent requests will include the key automatically

Swagger UI automatically adds the “Bearer ” prefix for JWT tokens and formats API keys correctly, so you only need to paste the raw token or key value.

Best Practices

Security Recommendations:

• Never expose API keys or tokens in client-side code or public repositories
• Use environment variables or secure vaults to store credentials
• Rotate API keys periodically, especially after team member changes
• Use JWT tokens for user-facing applications with automatic refresh logic
• Use API keys for server-side automations and long-running scripts
• Always use HTTPS in production to encrypt credentials in transit

Example: Token Refresh Logic

Implement automatic token refresh in your application:

import requests
from datetime import datetime, timedelta

class DispatcharrClient:
    def __init__(self, base_url, username, password):
        self.base_url = base_url
        self.username = username
        self.password = password
        self.access_token = None
        self.refresh_token = None
        self.token_expires_at = None
        self._authenticate()
    
    def _authenticate(self):
        response = requests.post(
            f"{self.base_url}/api/accounts/token/",
            json={"username": self.username, "password": self.password}
        )
        data = response.json()
        self.access_token = data["access"]
        self.refresh_token = data["refresh"]
        # Tokens typically expire after 5 minutes
        self.token_expires_at = datetime.now() + timedelta(minutes=5)
    
    def _refresh_token(self):
        response = requests.post(
            f"{self.base_url}/api/accounts/token/refresh/",
            json={"refresh": self.refresh_token}
        )
        data = response.json()
        self.access_token = data["access"]
        self.token_expires_at = datetime.now() + timedelta(minutes=5)
    
    def _get_headers(self):
        # Refresh token if it's about to expire
        if datetime.now() >= self.token_expires_at - timedelta(seconds=30):
            self._refresh_token()
        
        return {"Authorization": f"Bearer {self.access_token}"}
    
    def get_channels(self):
        response = requests.get(
            f"{self.base_url}/api/channels/",
            headers=self._get_headers()
        )
        return response.json()

# Usage
client = DispatcharrClient(
    "http://your-server:8000",
    "your_username",
    "your_password"
)
channels = client.get_channels()

Accounts API Endpoints

Key authentication-related endpoints:

Endpoint	Method	Description
/api/accounts/token/	POST	Obtain JWT token pair
/api/accounts/token/refresh/	POST	Refresh access token
/api/accounts/auth/login/	POST	Alternative login endpoint
/api/accounts/auth/logout/	POST	Logout (client-side token removal)
/api/accounts/api-keys/	GET	List API keys (admin/own keys)
/api/accounts/api-keys/	POST	Generate new API key
/api/accounts/api-keys/{id}/	DELETE	Revoke API key
/api/accounts/users/	GET	List users (requires permissions)
/api/accounts/permissions/	GET	List available permissions

For complete endpoint documentation, visit the Swagger UI.

Next Steps

• Explore the API Overview for available endpoints
• Visit the Interactive API Documentation to test endpoints
• Review endpoint-specific documentation for detailed request/response schemas