Authentication and API keys

Every request to the Revoye Cloud API carries Authorization: Bearer revoye_sk_live_…. Keys are created in the dashboard, shown exactly once, scoped to a subset of the API, and revocable immediately. There is no other authentication mechanism on the public API — no OAuth flow, no signed request.

Authorization: Bearer revoye_sk_live_3xQ8vP2mK9wR7tY4nL6jH1sD5fG0aZbC

Creating a key

Sign in → API keys → Create key. Your email address must be verified first. Choose a name you will recognise in six months (billing-worker-prod, not key 2, up to 80 characters) and the scopes it needs.

The secret is displayed once. Revoye Cloud stores a hash of it, so no endpoint exists that could return it — not to you, not to support, not to an attacker with a copy of the database. The dashboard keeps the first few characters so you can tell one key from another in a list, and shows when each key was last used.

What the key looks like

revoye_sk_live_3xQ8vP2mK9wR7tY4nL6jH1sD5fG0aZbC
└──────┬─────┘
       └─ a vendor prefix, on purpose

The prefix is not decoration. Secret-scanning services match on registered prefixes, so a key pushed to a public repository can be detected and flagged rather than sitting there working. It also makes a leaked key greppable in your own logs and history. A value that does not start with the prefix is refused before any lookup.

Scopes

A new key gets all three by default. Narrow them:

• A key embedded in a service that only submits work can be write-only — it can submit and cancel jobs but cannot read results back.
• A monitoring integration should be read-only — status:read alone.

A request that authenticates but lacks the scope gets 403 FORBIDDEN, not 401. The distinction matters when you are debugging: 401 means the credential is wrong, 403 means the credential is right and the permission is not.

What an API key can never do

An API key reaches the public /v1 API and nothing else. It cannot:

• create, rotate or revoke an API key
• change your password, email address or account settings
• read or change anything in the dashboard

Those are available only when you are signed in to the dashboard. The consequence is the one that matters: a leaked API key cannot escalate into account control. Whoever has it can submit jobs against your hourly limits and queue until you revoke it, and that is the whole of the blast radius.

Rotation

Rotate in the dashboard creates a replacement key with the same scopes and shows its secret once. The old key keeps working for 24 hours and then stops, so you can deploy the new one without an outage:

1. Rotate the key and store the new secret.
2. Deploy it.
3. Confirm traffic on the new key — the dashboard shows when each key was last used.
4. Revoke the old one, or let the 24 hours run out.

Revoke takes effect immediately — a revoked key stops working on the next request. There is no grace period, which is why you deploy the replacement first.

Rotate on a schedule you can actually keep, and rotate immediately on any suspicion: a key in a log, a repository, a screenshot, a support thread, or a laptop you no longer control.

Storing a key

• Environment variables or a secret manager. Never a committed file, never a client bundle, never a mobile app binary.
• One key per deployment, not one key shared across everything. A key you cannot revoke without taking down four systems is a key you will not revoke.
• Never log the Authorization header. If your framework logs headers by default, redact it explicitly.

If a key does leak: revoke it first, then investigate. Revoking is instant and free; the investigation is neither.

Errors