Authentication¶
Every API request carries an API key as a bearer token:
Header
Authorization: Bearer YOUR_API_KEY
API keys start with rvn_live_ and belong to one organisation. Everything a key can see or change is within that organisation.
API keys¶
Create a key¶
- In the app, open Settings → API.
- Under API Keys, select Create Key.
- Give the key a name that says where it's used, such as
CI pipeline. - Choose its permissions. A new key starts with read only.
- Optionally, set an expiry, and restrict the key to the IP addresses or ranges that will use it.
The key is shown once, when you create it: This is the only time this key will be displayed. Copy it and store it securely.
Revoke a key¶
If a key is no longer needed, or might have been exposed, revoke it in Settings → API and create a replacement. Requests made with a revoked key are refused.
Scopes¶
| Scope | Allows |
|---|---|
read |
Every GET request: reading missions, findings, assets, reports, usage and webhooks |
write |
Everything read allows, plus changes: starting, cancelling, pausing and resuming missions, updating findings, adding assets, and managing webhooks |
admin |
Everything read and write allow |
Give each key the smallest scope that does its job.
Error responses¶
| Status | Message | What to do |
|---|---|---|
401 |
Authorization header required |
Send the Authorization header. |
401 |
Invalid auth header |
Use the form Bearer YOUR_API_KEY. |
401 |
Invalid API key format |
Check the key was copied in full. |
401 |
Invalid API key |
The key isn't recognised. If it was revoked or has expired, create a new one. |
403 |
API key missing required scope: write |
Use a key with the scope the request needs. |
403 |
IP address not in allowlist for this API key |
Call from an address the key allows, or change the key's allowlist. |
403 |
A message about your plan | API access isn't included in your organisation's plan. Settings → Membership shows the plan. |
Keeping keys safe¶
- Keep keys in a secret store or environment variables, never in source code.
- Use one key per integration, so you can revoke one without affecting the others.
- Set an expiry on keys used by automation.
- Settings → API → Audit Log lists recent requests made with your keys.