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

header
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://platform.rivenai.io, authenticated with your Riven sign-in token (the OIDC access token issued by auth.rivenai.io for audience https://api.rivenai.io).

POST/v1/keys/developer

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.

request
curl -X POST https://platform.rivenai.io/v1/keys/developer \
  -H "Authorization: Bearer $RIVEN_SIGNIN_TOKEN" \
  -H "Content-Type: application/json" -d '{}'
response
{ "key": "rvn_...", "plan": "free" }

POST/v1/keys/developer/rotate

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.

request
curl -X POST https://platform.rivenai.io/v1/keys/developer/rotate \
  -H "Authorization: Bearer $RIVEN_SIGNIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key": "rvn_<current key>"}'
response
{ "key": "rvn_<new key>", "plan": "free", "rotated": true }

POST/v1/keys/developer/revoke

Deactivates your key without issuing a replacement.

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

GET/v1/keys/developer

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.

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

Handling keys safely