Authentication

Every connection is checked live when it opens. There is no long-lived signed token: the server looks your credential up on each connect, so a revoked key stops working on its next connection, not when some token expires.

API keys

• Format: opa_ followed by 32 random URL-safe characters, for example opa_3mZ….
• We store only a SHA-256 hash of each key. We cannot show you a key again: if you lose one, revoke it and issue a new one.
• A key belongs to your team. You can have several (one per environment is a good habit) and revoke any of them independently.

Sending the key

Server-side clients send it as a header:

Authorization: Bearer opa_your_key_here

Authorization: apikey opa_… and a bare key in the header are accepted too.

If your client cannot set headers, put the key in the connect payload instead:

{ "key": "opa_your_key_here" }

In the Centrifugo clients that is the data option (data={"key": KEY} in Python, data: { key } in JavaScript). If both are present, the header wins.

Browser tokens

Never ship an opa_ key to a web page; anyone can read it from the network tab. Instead:

1. Your backend holds the key and exchanges it for a short-lived token (prefix opt_).
2. The browser connects with that token in the connect payload, data: { key: token }.
3. Tokens live for 2 minutes. When one expires the connection is refused with code 4501; fetch a fresh token and reconnect.

A token carries exactly the same entitlements as the key behind it, and stops working the moment that key is revoked.

Coming soon

Self-service token minting for customer backends ships with the Dashboard. During the private preview, ask us and we will set it up for your origin.

Refusals

Missing, wrong, expired and revoked credentials all get the same answer — disconnect code 4501 with reason invalid api key (or no api key if none was sent). This is deliberate: the response cannot be used to probe whether a key exists. See Errors.