↓
Rivya AI Docs

API key authentication

Use Bearer API keys with the Rivya Public API. Learn how to create keys, check permissions, handle expiry, and revoke or rotate credentials.

Last reviewed on November 5, 2026

Use a Rivya API key to authenticate server-to-server requests to protected Public API endpoints.

The public model list at GET /api/v1/models does not require an API key. Reading the catalog does not grant permission to generate with a model.

An API key is not the same as a browser login session. Do not use cookies, Better Auth session state, or a personal browser token as a public API credential.

Header format

Send the full key in the Authorization header of each protected request over HTTPS. This is a header example; replace the placeholder with your key:

Authorization: Bearer rvya_sk_...

Put the key in the header, not in the request URL.

The full key is shown only once when created. Rivya stores a hash and a visible prefix, not the full secret.

Create a key

  1. Sign in to Rivya.

  2. Open API Keys settings.

  3. Enter a name of 1–80 characters and create the key. Settings assigns the fixed permissions listed below; there is no scope selector.

  4. Copy the full key immediately.

  5. Store it in a server-side secret manager or environment variable.

Do not put the key in client-side JavaScript, mobile app bundles, public repos, analytics events, or logs.

Current scopes

New keys created in Settings receive all nine scopes below. You cannot select a subset or edit an existing key's scopes in this UI.

  • models:read — Included in new Settings keys. GET /api/v1/models is currently public and does not check this scope.

  • generations:create — Submit generation requests with supported, callable models.

  • generations:read — Read and refresh generation tasks owned by the key's account.

  • files:create — Upload supported reference files for the key's account.

  • files:read — Read metadata for an available file owned by the key's account.

  • credits:read — Read the account's current credit balance.

  • webhooks:manage — Manage API webhook endpoints, signing secrets, and delivery records. The webhook feature must also be enabled.

  • chat:create — Send chat requests or streams to supported chat models.

  • chat:read — List API-created chat sessions and read their committed messages for the key's account.

An API key uses the credits and resource ownership of the account that created it. A scope grants the listed operation, not access to another account's tasks, files, or API chat sessions.

If an older key lacks a required scope for Files API, API Webhooks, or Chat API, create a replacement key and update your server configuration. Settings does not add permissions to an existing key.

Key expiry

Keys created in Settings currently have no automatic expiry, and the form does not let you set an expiry date. If a key has a configured expiry time, protected requests reject it at or after that time with api_key_expired.

A key also stops authorizing requests when revoked or when its owner's account is banned. Valid scopes do not enable a disabled API feature.

Revoke and rotate

Revoking a key changes its status so later authenticated requests are rejected. It does not cancel generation tasks that have already been accepted.

For a planned rotation, create and securely store a replacement key, update your server configuration, verify it with GET /api/v1/credits, then revoke the old key. Settings has create and revoke actions; it does not replace a key in place.

If a key is exposed, revoke it first, then replace it:

  1. Revoke the exposed key from API Keys settings.

  2. Create a new key and save its full secret.

  3. Update your server-side secret.

  4. Confirm the new key works with GET /api/v1/credits.

  5. Remove the old key from build systems, logs, and deployment variables.

A successful credits request confirms authentication and the credits:read scope. It does not verify generation, file, chat, or webhook access.

Revoked keys return api_key_revoked on later protected requests.

Authentication errors

Protected endpoints return errors in an error object with code, message, and, when available, requestId. Use the code to decide the next step:

  • api_key_missing (401) — No usable Bearer token was supplied. Send the full key in the Authorization header.

  • api_key_invalid (401) — The key's format, prefix, or secret did not match a key for an existing account. Check that you copied the full key.

  • api_key_revoked (401) — The key is no longer active, or its account is banned. Replace a revoked key; account restrictions must be resolved separately.

  • api_key_expired (401) — The key has reached its configured expiry time. Use a valid replacement key.

  • api_scope_denied (403) — The key lacks the endpoint's required scope. Replace an older key that lacks the current default permissions; Settings does not edit existing scopes.

  • public_api_disabled (503) — Authenticated API access is disabled for the deployment, or key hashing is not configured. API webhook routes also use this code when their separate feature switch is off. A new key cannot enable a disabled feature.

See API Errors and Limits for the full public error table.