skip to content

How must an OAuth 2.0 authorization server treat the `token_type_hint` parameter on an RFC 7009 revocation request?

level: middleimportance: should knowfreq 44%

answer

  1. a hint, not an instruction
  2. two registered values only
  3. a wrong hint costs a lookup
  4. MUST extend the search, MAY ignore
  5. unsupported_token_type means something else

basics

~20 s

token_type_hint is an optimisation, never a filter. A server that cannot find the token under the hinted type must extend its search across all the token types it supports, and it may ignore the hint altogether.

solid answer

~50 s

`token_type_hint` is OPTIONAL and tells the authorization server which kind of credential it is probably being given, with the registered values `access_token` and `refresh_token`. Its effect is on the lookup, not on the outcome. If the server cannot locate the token under the hinted type it **MUST extend its search across all the token types it supports**, and it **MAY ignore the parameter entirely**, particularly when it can recognise a token's type by itself. So a client that mislabels a refresh token as an access token still gets that refresh token revoked; it has only cost the server an extra lookup. RFC 7662 reuses the same parameter and the same rule on the introspection endpoint. Do not confuse a wrong hint with `unsupported_token_type`, which means something quite different: the server does not revoke tokens of the type presented at all.

code

http · 8 lines
http
POST /oauth2/revoke HTTP/1.1
Host: as.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3

token=45ghiukldjahdnhzdauz&token_type_hint=access_token

HTTP/1.1 200 OK

go deeper

for a junior

Recall that the hint is optional and that the two registered values are access_token and refresh_token. If you are unsure which kind of credential you hold, send no hint and the call still works.

for a middle

Explain both rules in the right direction: the server must widen its search when the hint fails, and may ignore the hint entirely. Then separate that from unsupported_token_type, which is about types the server will not revoke.

for a senior

Show why an advisory hint is the safer design — the caller most likely to mislabel a credential is the one who most needs the revocation to land — and make sure your client's error handling does not treat a successful mismatched call as a failure.

for a principal

Use it as an example of a protocol keeping a security outcome independent of a field clients get wrong, and apply the same test to optional parameters in interfaces your own platform publishes.

## Why a hint exists at all An authorization server may keep access tokens and refresh tokens in different places, and it is handed only an opaque string. Without help it may have to look in several places before it recognises what it was given. `token_type_hint` lets the caller say where to start. It is OPTIONAL on both the RFC 7009 revocation request and the RFC 7662 introspection request, and its registered values are `access_token` and `refresh_token`. The entire design intent is **performance**. That single sentence is what the question is testing, because the natural reading of the name is the opposite: people hear "type hint" and imagine a declaration the server enforces. ## The two normative rules 1. **MUST extend the search.** If the server cannot locate the token using the given hint, it has to search across all of its supported token types. A wrong hint therefore delays the answer; it does not change it. 2. **MAY ignore the hint.** A server able to detect the token's type on its own is free to disregard the parameter completely. Put together, the parameter is advisory in both directions: the server need not use it, and if using it fails, it must carry on without it. | the hint | what the server does | |---|---| | absent | searches the token types it supports | | correct | looks in the hinted type first and finds the token | | wrong | fails there, then extends the search across its supported types | | a value it does not recognise | narrows nothing; the search proceeds as if the hint were absent | ## The consequence clients actually care about A client that has lost track of which string is which can still call the endpoint. Suppose an application stored two credentials and revokes what it believes is an access token, hinting `access_token`, but the string is really a refresh token. The server looks among access tokens, finds nothing, extends the search, finds the refresh token, and revokes it. The client receives the ordinary empty `200`. **Nothing about the result depended on the hint being right.** This is also why sending no hint at all is a perfectly conforming choice. It costs the server a wider search and costs the client nothing in correctness. ## The error that is not about the hint `unsupported_token_type` is the trap. It does **not** mean "your hint was wrong" or "your hint value is unknown". It means the authorization server **does not support revoking tokens of the type that was presented** — the classic case being a server that revokes refresh tokens but not access tokens, answering a client that tried to revoke an access token. The distinction matters because the two situations call for different reactions: - **Wrong hint** — nothing to do; the revocation happened anyway. - **`unsupported_token_type`** — the credential is still live, and the client must either revoke the other credential in the pair or accept that this one dies only at expiry. ## Related misreadings to avoid - **Treating the hint as required.** It is optional on both endpoints; omitting it is not an error. - **Believing the hint scopes the effect.** It scopes the lookup. There is no combination of parameters that says "revoke this only if it is an access token". - **Expecting an error for a mismatch.** The server is obliged to find the token anyway, so a mismatch produces the ordinary successful response. - **Assuming the hint controls the cascade.** What other credentials go down with the one you revoked is decided by the *actual* type of the token found and by the grant behind it, never by the string you put in the hint. ## Why the specification chose this shape An optimisation that could silently change the result would be a footgun: the one caller most likely to send a wrong hint is the one least certain about what it is holding, which is exactly the caller who most needs the revocation to work. Making the hint advisory keeps the security-relevant outcome independent of a field the client may get wrong, and confines the cost of a mistake to one extra lookup.

  • What does a client gain by sending `token_type_hint` at all?
    A faster answer. A server that stores access and refresh tokens separately can look in the right place first instead of searching everywhere. The outcome is identical either way, so the parameter buys work saved on the server, not correctness for the client.
  • Which values may `token_type_hint` take?
    The two registered by RFC 7009, `access_token` and `refresh_token`. The registry is extensible, so a server may understand others, but a value it does not recognise simply narrows nothing and the lookup proceeds as though no hint had been sent.

saying these in an interview costs you the question

  • Treats token_type_hint as a required parameter.
  • Believes a wrong hint makes the server miss the token.
  • Thinks unsupported_token_type means the hint value was unrecognised.
  • Assumes the server is obliged to honour the hint it was given.
  • Says the hint decides which other tokens are revoked.