Authentication and API keys

Every request to the Revoye 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 session, no signed request.

Authorization: Bearer revoye_sk_live_3xQ8vP2mK9wR7tY4nL6jH1sD5fG0aZbC

Creating a key

Sign in → API keys → Create key. Choose a name you will recognise in six months (billing-worker-prod, not key 2) and the scopes it needs.

The secret is displayed once. Revoye 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 database. The dashboard keeps the first few characters so you can tell one key from another in a list.

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.

Scopes

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

• A key embedded in a client application should be write-only — it can submit work but cannot read back anyone's results.
• 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 API and nothing else. It cannot:

• create another API key
• pair or revoke a device
• change a provider, an agent, a rate limit or a rotation strategy
• read your audit log
• change anything about your account

Those are session-only operations in the dashboard. The consequence is the one that matters: a leaked API key cannot escalate into account control. Whoever has it can spend your agents' time until you revoke it, and that is the whole of the blast radius.

Rotation

1. Create the new key.
2. Deploy it.
3. Confirm traffic on the new key in the dashboard.
4. Revoke the old one.

Revocation takes effect immediately, not after a cache expiry — a revoked key stops working on the next request. There is no grace period, which is why step 3 comes before step 4.

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