Authentication

TorrPlay secures its API and streaming endpoints using two authentication methods, configurable via the /api/v1/settings endpoint.

By default, authentication is disabled.

Authentication Types

Basic Authentication (basic)

Requires username and password with every protected API request via the standard HTTP Authorization: Basic ... header.

Bearer Token Authentication (bearer)

Token-based authentication using JSON Web Tokens (JWT). Protected API requests pass the JWT in the Authorization: Bearer <token> header.

Usernames must contain 4–64 characters and passwords 4–128 characters.

Enabling Authentication

curl -X PATCH http://localhost:8090/api/v1/settings \
  -H "Content-Type: application/json" \
  -d '{
    "auth": {
      "enabled": true,
      "type": "basic",
      "username": "your-username",
      "password": "your-password"
    }
  }'

curl -X PATCH http://localhost:8090/api/v1/settings \
  -H "Content-Type: application/json" \
  -d '{
    "auth": {
      "enabled": true,
      "type": "bearer",
      "username": "your-username",
      "password": "your-password"
    }
  }'

Obtaining a Token (Bearer Auth)

The /oauth/token endpoint is available when bearer auth is enabled:

curl -X POST http://localhost:8090/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password&username=your-username&password=your-password"

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

Access tokens expire after 24 hours. The token endpoint and /api/system/health are public so clients can sign in and check whether TorrPlay is available.

Updating Authentication Settings

GET /api/v1/settings never returns the password. When updating other authentication fields, omit password from the PATCH /api/v1/settings request to keep the current password.

Changing any authentication setting—including enabling or disabling authentication, changing its type, or updating credentials—revokes all active access, playback, and Stremio tokens.

Scoped Playback Tokens

When authentication is enabled (either Basic or Bearer), streaming endpoints (/api/v1/stream/*), playlist generation (/api/v1/playlist), and Stremio streams require authentication.

To support external media players (such as VLC, Infuse, Kodi, or Smart TVs) without exposing full administrative credentials or passing admin tokens in URL query strings, TorrPlay provides scoped playback delegation tokens:

Creating a Playback Token

Endpoint: POST /api/v1/tokens

curl -X POST http://localhost:8090/api/v1/tokens \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{"scope": "playback"}'

(For Basic Auth, supply -u your-username:your-password instead of the Bearer header).

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "scope": "playback",
  "expires_at": "2026-09-11T16:00:00Z"
}

Playback tokens expire after 24 hours.

Using Playback Tokens in Media URLs

Pass the token as a token query parameter in streaming and playlist URLs:

http://localhost:8090/api/v1/stream/{hash}?path=video.mp4&token=your-playback-token
http://localhost:8090/api/v1/playlist?token=your-playback-token

Making Authenticated API Requests

With a Bearer Token

Include the JWT token in the Authorization header:

curl -H "Authorization: Bearer your-jwt-token" http://localhost:8090/api/v1/torrents

With Basic Auth

Use the -u flag with curl:

curl -u your-username:your-password http://localhost:8090/api/v1/torrents

Recovery: Disabling Authentication

If you forget your credentials, you can temporarily bypass authentication by restarting TorrPlay with the TORRPLAY_DISABLE_AUTH environment variable:

TORRPLAY_DISABLE_AUTH=true ./torrplay --data-dir=./data

This allows full API access without credentials. Update your credentials or disable authentication via PATCH /api/v1/settings, then remove the environment variable and restart normally.