Last updated
Authentication
Every request carries a workspace API key as a Bearer token. Keys are scoped, revocable and tied to one workspace’s credit wallet.
Bearer keys
Send the key in the Authorization header. Keys are created in the dashboard under Settings → API keys; the secret is shown once.
curl "https://api.roomscope.io/v1/rankings/regions" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"One wallet
A key spends the credits of the workspace that owns it. Usage from the API and from the dashboard appear together under Settings → Usage.
Scopes
A key can only call endpoints covered by its scopes. Pick the smallest set that does the job; you can always create a second key. Requests outside the key’s scopes return 403 with code forbidden.
| Scope | Grants |
|---|---|
live:read | LIVE sessions, rooms and gift rollups |
live:stream | Real-time room events (streaming endpoints) |
rank:read | Official leaderboards and regions |
shop:read | Shopping boards |
gifter:read | Gifter rankings and totals |
creator:read | Creator profiles and changes |
content:read | Creator videos |
trend:read | Regional trends |
export | Create and download exports |
webhook:manage | Alert rules and webhook endpoints |
keys:manage | Create, rotate and revoke API keys |
Key rotation
Create the replacement key first, deploy it, then revoke the old one from the same screen. Revocation is immediate: in-flight requests finish, new ones fail with 401.
A grace period during which both keys stay valid is planned. Subject to change
Errors
| Status | Code Subject to change | Meaning |
|---|---|---|
| 401 | unauthorized | Missing, malformed, revoked or expired key. |
| 403 | forbidden | The key is valid but lacks the scope, or the workspace’s plan does not include the resource. |
| 402 | payment_required | The wallet is empty or the plan does not allow fresh reads. See Errors. |
Was this page helpful?