Guides

Authentication

Every billable call carries a secret: an rd_sk_… API key, or an access token from "Sign in with RodiumAI". Keep both server-side.

API keys

Create keys in Dashboard → API keys. The full secret is shown once; RodiumAI only stores its hash.
Production keys look like rd_sk_prod_…, development keys like rd_sk_dev_…. The gateway accepts any key that starts with rd_sk_; anything else is rejected with 401 invalid_api_key.
Each key bills your account and inherits its balance. You can hold several active keys (the dashboard shows the cap), one per app or environment.

Sending the key

Send the key as a Bearer token. This is what the OpenAI SDKs do when you set api_key / apiKey.

…

x-api-key: rd_sk_… (the Anthropic SDK style) is accepted only on POST /v1/messages (and /v1/messages/count_tokens) and POST /v1/audio/*. Every other route needs Authorization: Bearer and answers 401 invalid_api_key when only x-api-key is sent. When both headers are present, Authorization wins.

…

GET /v1/models, GET /v1/models/{id} and GET /v1/models/coding are public: no credential needed. When you do send a key to /v1/models, the list is filtered to the models that key may use.

Key options

Option	Effect	When it blocks a request
Allowed models	The key can only call these ids. Smart routing and rule profiles only pick among them; a custom model passes if its slug or its base model is listed.	`403 model_not_allowed` (or `403 smart_pool_empty`, `404 profile_empty`)
Monthly RODI quota	Caps what the key may spend per monthly cycle. Empty or `0` means unlimited. The check runs before each request, so concurrent requests can overshoot slightly.	`403 api_key_quota_exceeded`
Billing source	`main` spends your wallet. `provided` spends a provided-credit allotment limited to some providers, and falls back to the main wallet when the allotment cannot cover the request.	`402 insufficient_balance`
Scopes	Keys created in the dashboard carry no scope restriction. Keys with explicit scopes need `chat:write` for chat, messages, responses, images, video and audio, and `embeddings:write` for embeddings.	`403 insufficient_scope`
Expiry	Some keys issued by RodiumAI carry an expiry date.	`401 invalid_api_key` after expiry
Rate limits	Per-key RPM/TPM values set by RodiumAI replace the defaults when a model has no limit of its own. See Rate limits.	`429 rate_limit_exceeded`

Rotation and revocation

Revoke a key from the dashboard as soon as it may have leaked (CI logs, client bundles, shared screenshots), then create a new one.
Revocation is applied right away, but allow up to about 60 seconds for every gateway instance to stop accepting the key: key lookups are cached for that long. The same delay applies to changes of allowed models, quota or billing source.
To rotate without downtime, create the new key, deploy it, then revoke the old one.

Sign in with RodiumAI (OIDC)

Apps registered with RodiumAI can let users sign in with their RodiumAI account and call the API on their behalf, without handling an rd_sk_ key. RodiumAI acts as an OpenID Connect provider; the endpoints are listed in its discovery document at https://rsb.rodiumai.io/.well-known/openid-configuration.

Client registration is done by RodiumAI: contact us to get a client_id (rd_oidc_…), your redirect URIs and the scopes your app may request.
Use the authorization-code flow with PKCE (S256): GET /api/v1/oauth/authorize, then POST /api/v1/oauth/token. Access tokens are RS256 JWTs valid for 1 hour; refresh tokens rotate and last 30 days.
Call the gateway with Authorization: Bearer <access_token>. JWTs are not accepted in x-api-key.

…

Scopes: the token needs inference (or forge.read) to call inference routes. Without it the gateway answers 401 insufficient_scope.
Billing: calls made with a user's access token spend that user's FRODI (Forge subscription credits), not a RODI wallet. An active Forge subscription is required; when the allotment cannot cover the hold the gateway answers 402 insufficient_balance. GET /v1/wallet does not apply to tokens.
Models: depending on the user's plan, a token may be limited to smart routing (rodiumai/smart and the rodium/* profiles).
Errors: an expired, badly signed or foreign token returns 401 invalid_token; refresh it and retry.

Security checklist

Keep keys in environment variables or a secret manager on the server; never in browser or mobile code, and never in NEXT_PUBLIC_* variables.
Use one key per app and environment, with allowed_models and a monthly quota, so a leak has a bounded cost.
Revoke compromised keys immediately and rotate regularly.
Never send your key to support; the X-Request-Id of a response is enough to investigate.

Header rules per route and authentication errors: API authentication.