Skip to content

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

  1. In the app, open Settings → API.
  2. Under API Keys, select Create Key.
  3. Give the key a name that says where it's used, such as CI pipeline.
  4. Choose its permissions. A new key starts with read only.
  5. 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.