Authentication & keys

Every API request is authenticated with a bearer key. Keys are prefixed rvn_, are scoped to your plan, and carry your rate limits and monthly quota with them.

Using a key#

Authorization: Bearer rvn_...

Missing or unknown keys return HTTP 401 with NO_AUTH / INVALID_KEY — see Errors.

Key lifecycle#

The console at console.rivenai.io is the primary place to manage keys. The same operations are available programmatically at https://api.rivenai.io, authenticated with your Riven sign-in token (the OIDC access token issued by auth.rivenai.io for audience https://api.rivenai.io) — see Riven Auth.

Mints your developer API key, scoped to your current plan. Idempotent — calling it again returns your existing active key rather than creating a new one.

curl -X POST https://api.rivenai.io/v1/keys/developer \
  -H "Authorization: Bearer $RIVEN_SIGNIN_TOKEN" \
  -H "Content-Type: application/json" -d '{}'

{ "key": "rvn_...", "plan": "free" }

Replaces your key with a fresh value. The old key stops working immediately; plan, quota standing, and usage history carry over to the new key.

curl -X POST https://api.rivenai.io/v1/keys/developer/rotate \
  -H "Authorization: Bearer $RIVEN_SIGNIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key": "rvn_<current key>"}'

{ "key": "rvn_<new key>", "plan": "free", "rotated": true }

Deactivates your key without issuing a replacement.

curl -X POST https://api.rivenai.io/v1/keys/developer/revoke \
  -H "Authorization: Bearer $RIVEN_SIGNIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key": "rvn_<current key>"}'

Lists your developer keys (values masked to a prefix).

Guest access (device-scoped)#

For try-before-signup flows, a device can mint a tightly rate-limited guest key without an account. Guest keys are capped per-device and can only use guest-tier models — production workloads should use a developer key.

curl -X POST https://api.rivenai.io/v1/keys/guest \
  -H "Content-Type: application/json" \
  -d '{"device_id": "<stable unique device identifier>"}'

{ "key": "rvn_...", "plan": "guest-device", "rate_limit_per_day": 7200 }

Minting is idempotent per device_id — repeat calls return the same key.

Plans, limits, and keys#

• A key inherits its plan at mint time; upgrading your plan upgrades what your key can do.
• Per-minute rate limits and model availability come from the plan — see Models & usage.
• Monthly quota is tracked per account and surfaced on GET /billing/quota and the x-riven-quota-* response headers.

Handling keys safely#

• Store keys in environment variables or a secret manager — never in source control or client-side code.
• Use guest keys, not your developer key, in anything that ships to end-user devices.
• Rotate immediately if a key may have leaked; rotation is instant and preserves your plan and quota.