API keys and tokens

Everything in the web app goes through the REST API, and tokens let your own scripts and tools use it. There are two kinds:

• Service keys act for the workspace with a role, for integrations (a PSA sync, a reporting job). Owners and admins manage them in Settings → API keys.
• Personal tokens act as you: no more than your own role allows, and they stop working if your account is turned off. Anyone on the team makes their own in Settings → Personal tokens, or with revo login.

Create a service key

1. Settings → API keys → New service key. Name it after what uses it ("Nightly findings export").
2. Choose its role: Analyst (read-only), Technician or Admin. You can only use a role you're allowed to assign.
3. Under What it may do, keep Everything the role allows, or pick Only what I pick and tick the permissions it needs. Pick as few as work.
4. Create it. The key (rsk_…) is shown once: copy it into your secret store straight away.

Keys expire (after a year by default). The list shows every token in the workspace, including your team's personal tokens, with its kind, role, permissions, last use and expiry. Revoke one when it's no longer needed or may have leaked; it stops working at once. Creating and revoking tokens is recorded in the audit log.

Personal tokens

Settings → Personal tokens → New token: name it, choose how long it lasts (up to 90 days) and what it may do, and confirm with your two-factor code. The token is shown once.

The revo command-line tool

revo signs in with your account and calls any API operation:

revo login --url https://revosecure.example.com     # shows a code; approve it in the browser
revo whoami
revo ops alerts                                      # find operations
revo call list_alerts_api_v1_rmm_alerts_get state=all
revo api GET /customers

revo login prints a code and a link to /device. Open it while signed in, check the code matches your terminal, and approve with your two-factor code. The tool gets a personal token for 30 days. Add --scope findings:read (one or more times) to limit it.

revo mcp serves the API to AI agents as MCP tools (read-only unless you add --allow-writes); the token's permissions still apply.

Use a token

Send it as a bearer token:

curl -H "Authorization: Bearer rsk_..." \
  "https://revosecure.example.com/api/v1/findings?severity=critical"

• All endpoints are under /api/v1 and exchange JSON. No CSRF token is needed with a token.
• Errors are {"detail": "..."} with standard status codes: 401 not authenticated, 403 missing permission, 402 plan limit, 409 conflict, 422 validation, 429 rate limited (honour Retry-After).
• Repeat-safe writes: send Idempotency-Key: <any unique string> with a POST, PUT, PATCH or DELETE. If the request is sent again with the same key within 24 hours, you get the first answer back instead of doing it twice.

The full reference (Swagger UI and ReDoc) is at /api/docs and /api/redoc on your address; sign in, or send a token, to open it.

What tokens can't do

No token can run scripts on devices, approve scripts, manage API keys or manage people (invite, change or remove team members): those need a person at the keyboard. Some other actions need a person with two-factor authentication too, such as turning on patch management for a customer. Tokens never see other workspaces.