API tokens and OpenAPI
Issuing tokens with limited scopes for scripts, MCP and bots, the OpenAPI description of the API and error codes.
An API token gives MCP, a Telegram bot and your own scripts access instead of the instance key. A token has scopes: it opens only what you gave it. Passwords, 2FA codes and vault export are never available to a token; neither are settings, issuing tokens or pairing devices.
Issuing a token
Settings → Access → API tokens:
- A label, so you can recognise the token later, e.g. "Claude on the laptop".
- Preset — a ready set of scopes:
| Preset | Scopes |
|---|---|
| Finance MCP | fin:read, fin:write |
| Network MCP | crm |
| Telegram bot | telegram, banks, booking, assistant, fin:read, fin:write |
| Read only | fin:read, vault:read-meta, servers:read |
- Term — 30 days, 90 days, 1 year or no expiry.
- Issue. The token (
ocd_…) is shown once — copy it right away.
Revoke with "Revoke": a client using the token gets 401 immediately. A revoked token can't be brought back, only replaced with a new one.
Usage and limit
The chart button in a token's row opens its stats for 30 days: calls per day (errors and rate-limited calls in their own colour), the last call — time, request and the address truncated to its network (203.0.113.0/24), and the most frequent requests. Only counters per day and route template (GET /api/fin/accounts/:id) are kept — request bodies, parameters and values in the URL are never stored. Days are in UTC; stats are kept for 90 days.
Each token has a requests-per-minute limit, 300 by default. Change it right there in the token's stats: the new limit applies at once, no need to reissue the token. Above the limit the API answers 429 token_rate_limited with a Retry-After header — how many seconds to wait. A short burst up to the limit goes through, after that requests are let through evenly.
Scopes
| Scope | Opens |
|---|---|
fin:read | finance — read |
fin:write | finance — write (includes read) |
vault:read-meta | vault — list only, no secrets |
calendar | calendar |
tasks | tasks |
docs | documents (no deleting) |
servers:read | servers — read |
telegram | Telegram |
banks | bank sign-in — give it to the bot only |
booking | bookings |
assistant | assistant — a broad scope |
crm | network (contacts and leads) |
health | instance status |
API description (OpenAPI)
API reference — the /api-reference page of your instance (e.g. https://name.me.rivo.day/api-reference), no sign-in needed: every route with its parameters, a body example and a ready curl command, token scopes, error codes and limits. The dashboard links to it too — the Documentation button in the API tokens section shows a short description right there. The machine-readable file is at /api/openapi.json on your instance (e.g. https://name.me.rivo.day/api/openapi.json) and needs no sign-in. It's OpenAPI 3.1: import it into Swagger Editor, Postman or Insomnia.
The description covers only what tokens can reach: internal routes and sign-in aren't in it, and of the vault only the entry list without secrets.
Requests
export RIVO_URL=https://name.me.rivo.day
export RIVO_TOKEN=ocd_…
curl -H "Authorization: Bearer $RIVO_TOKEN" "$RIVO_URL/api/fin/summary"The reference examples use the same variables. An error is JSON with statusCode, code and message: branch on code, the message text may change.
| Response | Meaning |
|---|---|
401 device_revoked | the token is revoked or expired |
403 scope_forbidden | the route is outside the token's scopes — issue a token with the right scope |
409 time_busy | calendar: the time is taken (request with checkConflicts: true); the response lists conflicts and free slots |
429 token_rate_limited | the token's limit is exceeded — retry after Retry-After seconds |
429 rate_limited | too often — retry after retryAfter seconds |
The full list of codes (including plan_locked, module_disabled, vault_e2e_strict) and the limits are in the API reference.
Public booking works without a token — see Booking and webhooks. To connect Claude to your dashboard — MCP server.