Home / Knowledge hub / Opaque token
Knowledge hub
Opaque token
A token with no readable content, looked up on the server to find who it is for.
What it means
An opaque token is a random string that means nothing to anyone who holds it. It carries no name, role or expiry that a client can read. To learn what it stands for, the server looks it up in a store, or asks the authorisation server through token introspection, defined in RFC 7662.
Contrast this with a JWT, which carries its claims inside and is checked by its signature. An opaque token is a reference: a ticket number rather than a letter. All the facts live on the server, and the client can neither read nor edit them.
Why it matters
Because the server owns the facts, it can change them at once. Revoking a token, cutting a role or ending a session takes effect on the next request. Nothing about the user is exposed if the token leaks into a log or a screenshot, apart from what that token can do.
The cost is a lookup on every request, which means storage, speed and an extra point of failure. Many teams choose it for sessions and sensitive access, and signed tokens for short-lived service calls. Neither is automatically safe; weak generation or poor storage ruins either one.
How it shows up
Classic server-side session identifiers are opaque tokens. So are many API keys and OAuth access tokens, since RFC 6749 does not require a particular format. An API gateway often swaps a client's opaque token for an internal signed one after introspection. See session tokens and access tokens.
The mistakes repeat. Tokens too short or made from a predictable generator, an introspection endpoint open to anyone, results cached too long so revocation is slow, and tokens stored in plain text in the database. Hash stored tokens where possible, and test that revoked ones fail at once.
Questions people ask
Opaque token, answered
Is an opaque token more secure than a JWT?
Not automatically. It is easier to revoke and exposes no readable data, but it needs a lookup and depends on a strong generator and storage. A well-built JWT with short expiry is also sound.
The right choice depends on how fast you must revoke.
How does a server validate an opaque token?
It looks the value up in its own store, or sends it to an introspection endpoint that returns whether the token is active and what it allows.
That endpoint must itself be protected, so that only trusted servers can ask.
Can an opaque token be guessed?
Only if it is generated badly. A long value from a secure random source has too many possibilities to guess. One made from a counter or time can be predicted.
Should opaque tokens be stored hashed?
Where practical, yes. Storing a hash of the token means a database leak does not hand over working credentials, much as with passwords. Because the token is already high-entropy, a fast hash is enough.
Compare the hash of what arrives with what is stored.
Are API keys opaque tokens?
Usually they are. They are random strings the server maps to an account, with no meaning to the holder. The same care applies: generate securely, store hashed, scope them, and allow rotation.
See API keys.
Sources
Where this comes from
Related
Terms that sit next to this one
JWT
A signed token a client carries to prove who is signed in.
Session token
A random value the browser sends to show it belongs to a signed-in visit.
Access token
A short-lived token that lets a client call an API on a user's behalf.
API key
A secret string that identifies the app calling your API, and is easily leaked.
Token revocation
Cancelling a token before it expires, for example after a password change.
Can a stolen token be killed at once?
We check how tokens in your app are issued, looked up and revoked, and whether a revoked one still gets through. Each result comes with the request and response. Ask us to run it on one of your applications.
Or start with a $199 pilot on one application: thirty days, success criteria agreed before day one, credited against the annual if you convert.