Skip to content
scenemaDocs

Authentication

The API takes two kinds of credentials, both sent as an HTTP Bearer token:

  • A personal API key (sk_...) for your own scripts, servers and MCP tools. See The header below.
  • An OAuth access token for an app that acts for a Scenema user, such as a platform built on Scenema or an MCP client like Claude or ChatGPT. The user signs in to Scenema and allows access; there is no key to copy. See Acting for a Scenema user.

Both need the workspace to be on the Creator or Pro plan. The Scenema mobile app signs in as you and works on every plan.

The header

Send the key on every request as an Authorization header:

Authorization: Bearer sk_your_key_here

The header name is case-insensitive per HTTP convention; the value must start with Bearer followed by the raw key. The server strips the Bearer prefix, hashes the remainder, and looks the row up in constant time.

What a key looks like

Scenema keys are prefixed sk_ followed by 64 characters drawn from an alphabet the plugin picks at creation time. A full example:

sk_ONAzYeucfzSTYepxAhFAVpdoYCMQdqAmTpmbdxeRwYCYVOFQDLBhqfjXCcCzFrZC

The prefix identifies the key visually. The remainder is the secret; treat it like a password.

Key scope

Every key is anchored to the workspace that was active when you created it. Rate limits, entitlements, and credit charges follow that workspace’s plan, not the plan of whatever workspace you happen to be viewing when you make the call. Switching your active workspace in the app does not affect existing keys.

If your workspace’s plan changes (upgrade, downgrade, or cancellation), Scenema server-side rewrites the rate limit ceiling on every key anchored to that workspace within seconds. You never need to regenerate keys to pick up a new plan’s limits.

Security posture

  • Treat keys as sensitive credentials. Store them in a password manager, a .env file that is git-ignored, or your CI provider’s secret store.
  • Never commit keys to source control. Never paste them into support tickets or public issue trackers.
  • If you suspect a key is compromised, revoke it immediately from the Settings surface. Revoked keys stop working within seconds.

Testing a key

The simplest way to confirm your key works is to hit the “list your keys” endpoint:

Terminal window
curl -H "Authorization: Bearer $SCENEMA_KEY" \
  https://scenema.ai/api/service/user/api-keys
  • HTTP 200 with a JSON body: the key is valid, enabled, and under its rate ceiling.
  • HTTP 401 with Unauthorized: Authentication failed: the key is unknown, disabled, or expired.
  • HTTP 429 with code: RATE_LIMITED and a Retry-After header: the key is valid but the workspace has hit its rate limit. All keys on the workspace share one counter. See Rate Limits.

Acting for a Scenema user

An app that makes videos for its own users connects each of them to their Scenema account with OAuth 2.1. The user signs in to Scenema, sees what the app asks for and clicks Allow access; the app then calls the API with an access token that acts as that user, in the workspace they have open.

  1. Discover the endpoints at https://scenema.ai/.well-known/oauth-authorization-server. It lists the authorization, token and registration endpoints.

  2. Register your app once with Dynamic Client Registration (RFC 7591): POST https://scenema.ai/auth/mcp/register with your app’s name and redirect URIs. Keep the client_id it returns.

  3. Send the user to authorize at https://scenema.ai/auth/mcp/authorize with PKCE (code_challenge_method=S256), your client_id, redirect_uri, a state and the scopes you need. Scenema shows its consent screen every time.

  4. Exchange the code at https://scenema.ai/auth/mcp/token for an access token and a refresh token.

  5. Call the API with the access token:

    Authorization: Bearer <access token>

Scopes are the OpenID ones: openid, profile, email and offline_access (for a refresh token). Access tokens last 60 minutes. Refresh tokens rotate: each refresh returns a new pair and retires the old one, so store the new refresh token every time. An expired or revoked token gets HTTP 401; refresh it, or send the user through authorization again if the refresh fails.

The user’s workspace must be on Creator or Pro. On another plan, calls answer HTTP 403 with code: API_PLAN_REQUIRED; show the user that they need to upgrade their Scenema plan. Credits are charged to the user’s workspace, never to yours.