Authentication

The API uses OAuth 2.1 with the authorization-code grant and PKCE. Public clients (native apps, AI agents) must use PKCE; confidential clients created in the developer portal also receive a client_secret. Tokens are JWTs signed by our authorization server.

Endpoints

Scopes

• video:read - list videos, read render status, download completed videos.
• video:create - create videos (spends one export credit each).

1. Register an app

Create an app in My apps with one or more redirect URIs (https, or http on localhost) and your scopes. AI agents instead self-register via /oauth/register.

2. Authorize (with PKCE)

Generate a PKCE verifier and challenge, then redirect the user to:

GET https://nostalgija.net/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://your.app/callback
  &scope=video:read%20video:create
  &code_challenge=BASE64URL_SHA256_OF_VERIFIER
  &code_challenge_method=S256
  &state=RANDOM

The user logs in (if needed) and approves the requested scopes on the consent screen. We then redirect back to your redirect_uri with ?code=...&state=....

3. Exchange the code for a token

curl -X POST https://nostalgija.net/oauth/token \
  -d grant_type=authorization_code \
  -d code=AUTH_CODE \
  -d redirect_uri=https://your.app/callback \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d code_verifier=YOUR_PKCE_VERIFIER

Public clients omit client_secret. The response:

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJ...",
  "refresh_token": "def..."
}

4. Use the token

curl https://nostalgija.net/api/v1/videos/42 \
  -H "Authorization: Bearer eyJ..."

A missing or invalid token returns 401. A valid token that lacks the scope an endpoint requires returns 403.

5. Refresh the token

Access tokens live one hour. Use the refresh token (valid one month) to get a new one:

curl -X POST https://nostalgija.net/oauth/token \
  -d grant_type=refresh_token \
  -d refresh_token=def... \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET