API Authentication

Rivya API uses API keys for server-to-server access.

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 key in the Authorization header:

Authorization: Bearer rvya_sk_...

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. Create a key with the scopes you need.
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

The first version documents these scopes:

• models:read
• generations:create
• generations:read
• files:create
• files:read
• credits:read
• webhooks:manage
• chat:create
• chat:read

New keys created in Settings include the documented scopes by default. Older keys may need to be recreated before using Files API, API Webhooks, or Chat API.

Revoke And Rotate

If a key is exposed:

1. Revoke the old key from Settings.
2. Create a new key.
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.

Revoked keys return api_key_revoked.

Authentication Errors

Common authentication errors:

• api_key_missing
• api_key_invalid
• api_key_revoked
• api_key_expired
• api_scope_denied
• public_api_disabled

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

Related Pages

• API Quickstart
• API Credits
• API Errors and Limits
• Authentication and Access in Rivya