Skip to main content
Every request to the Ryvo API (except the public model catalog, GET /v1/models) has to be authenticated with a Bearer token. The tokens are called API keys and you manage them from the portal, under Settings > API keys (app.ryvo.so/developers). The API is available from the Starter plan up.

​
Header format

​
Create an API key

  1. Go to app.ryvo.so/developers.
  2. Click New API key.
  3. Give it a descriptive name (for example n8n production, my-crm-staging).
  4. Tick the scopes it needs (see below). A read-only key is enough for most reporting integrations.
  5. Copy the full token. It is shown only once, so store it in a secret manager.
The token looks like this:
Once you close the creation modal, we cannot show you the token again. If you lose it, revoke that key and create a new one.

​
Scopes

Each key carries a list of scopes in the form resource:action, chosen when you create it. Every endpoint requires exactly one scope, listed on its page in the API reference as x-scope. Calling an endpoint with a key that lacks it returns 403 insufficient_scope, and the message names the missing scope. Integrations, team and billing are read-only by design. GET /v1/me needs no scope and tells you which ones the key carries.

​
Revoke an API key

If a key leaks (say you committed it to a public repo), go to app.ryvo.so/developers, find the key in the list and click Revoke. From that moment on, any request with that key returns 401 unauthorized. The action is immediate and irreversible: there is no grace period.

​
How we store keys

  • We never store the token in the clear. We only keep an HMAC-SHA-256 hash plus a server-side pepper.
  • In the portal you only see the prefix (ryvo_live_abc123…) and the last time it was used.
  • Even if somebody got access to our database, the keys stay safe: the pepper lives only in environment variables and the hash cannot be reversed.

​
Best practices

Create a separate key for each CRM, n8n workflow or environment (staging vs production). If one is compromised, you revoke just that one without touching the rest.
Load the token from process.env.RYVO_API_KEY or the equivalent. Never write it straight into your source code.
API keys should only be used from your server. If you expose them to the frontend (browser, mobile app), any user can read them with DevTools.
Every 90 days, create a new key, update the integration and revoke the old one. If you suspect an incident, rotate right away.

​
Check that your key works

  • If the key is valid, you get 200 with your account, your plan and the scopes the key carries.
  • If the key is wrong or revoked, you get 401 unauthorized.
  • If you get a 401, check that the header is written correctly (Bearer with a space) and that the key has not been revoked in the portal.

​
Authentication errors