Deferred Token Response

Some authorization decisions take longer than a request

An application may have everything it needs to ask for access before the authorization server has everything it needs to grant it. A fraud analyst might need to review a transfer, a document owner might need to approve a service, or an automated check might still be running.

A token request normally ends with a token response or an error. DTR adds a defined way to keep that authorization decision pending: the server returns a deferral code, and the client checks for the eventual result.

The authorization server decides whether a particular request needs to wait. The same client can receive an immediate token for one request and a deferred response for another.

Three reasons a token might need to wait

Each scenario shows the client on the left, the authorization server on the right, and their request logs below. Start with the sample values, then change one thing and compare the result.

Request. Wait. Collect the result.

1. The client opts in.

   It includes completion_mode=deferred in its token request to signal that it can handle a deferred response.

2. The server defers the decision.

   It returns authorization_pending, a deferral_code, an expiry, and a minimum polling interval. No access token has been issued.

3. The client checks back.

   It sends the deferral code to the token endpoint. The server reports whether the request is still pending or needs an external interaction.

4. The request resolves.

   Approval allows the client to collect the token response. Denial or expiry ends the attempt without a token.

These examples use polling. The deferral code identifies a pending request; it does not grant access to the protected resource.

The OAuth terms used here

OAuth lets an application obtain limited access to a protected resource. These are the terms you will see in the demos:

DTR extends the token response process. The original grant still establishes the basis for the request; DTR handles what happens when the decision needs more time.

Further reading: OAuth overview · OAuth 2.1 draft

Follow a deferred token request

The examples below show the polling path. Client authentication and other grant-specific requirements still apply; they are omitted from these short examples.

1. Tell the server the client can wait

   The client includes deferred in the space-separated completion_mode parameter. Without that opt-in, the server must not defer the token response using DTR.

   POST /token HTTP/1.1
   Host: server.example.com
   Content-Type: application/x-www-form-urlencoded
   
   grant_type=authorization_code
   &code=example_authorization_code
   &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
   &completion_mode=deferred

   Opting in does not force a delay. The server can still return a token immediately. For grants with an earlier request step — the authorization request in the Authorization Code flow, for example — the client can also include this same opt-in there.

2. Receive a deferral code

   If the server needs more time, it returns an HTTP 400 OAuth error response with authorization_pending and the information needed to continue.

   HTTP/1.1 400 Bad Request
   Content-Type: application/json
   Cache-Control: no-store
   
   {
     "error": "authorization_pending",
     "deferral_code": "example_deferral_code",
     "expires_in": 10800,
     "interval": 60
   }

   Parameter	Meaning
   deferral_code	The opaque code used in later polls for this request. It must be handled according to the draft’s client-binding and security requirements.
   expires_in	Seconds until the deferral code expires. This is separate from an access token’s lifetime.
   interval	The minimum number of seconds between consecutive polls for this deferral code.
   interaction_uri	A location where an external actor can act on the request. Optional in the initial deferred response; required with interaction_required.

   The HTTP error format does not mean the authorization request has been denied. Here, it means the result is still pending.

3. Poll for the outcome

   The client sends the deferral code to the token endpoint using the deferred grant type, respecting the server’s polling interval. The server responds with a variety of error codes depending on the state of the request.

   POST /token HTTP/1.1
   Host: server.example.com
   Content-Type: application/x-www-form-urlencoded
   
   grant_type=urn:ietf:params:oauth:grant-type:deferred
   &deferral_code=example_deferral_code

   HTTP/1.1 400 Bad Request
   Content-Type: application/json
   Cache-Control: no-store
   
   {
     "error": "authorization_pending"
   }

   • authorization_pending Continue polling at the permitted interval. The server has not returned a final result.
   • interaction_required Present the supplied interaction_uri to the appropriate actor and continue polling at the permitted interval.
   • slow_down Increase the polling interval by at least five seconds before continuing.
   • expired_token Stop polling this code. Start a new flow if access is still needed.
   • access_denied Stop polling. The request was denied or cancelled.
   • invalid_grant Stop polling this code. It may be unknown, invalid for this client, or already redeemed.

   Pending authorization responses and polling errors are different concepts. A pending request can change state while the client waits; slow_down tells the client to change its polling behavior. Denial, expiry, and invalid-grant responses end this polling attempt.

4. Collect the token response

   Once authorization is approved, a successful poll returns the token response the original grant would have produced.

   HTTP/1.1 200 OK
   Content-Type: application/json
   Cache-Control: no-store
   
   {
     "access_token": "example_access_token",
     "token_type": "Bearer",
     "expires_in": 3600
   }

   The deferral code is single-use. After it has been redeemed for a token response, another poll with that code returns invalid_grant.

How does this relate to Device Authorization and CIBA?

Other OAuth and OpenID Connect flows also support waiting for an external action. The distinction is where that waiting fits into the flow.

Device Authorization is a dedicated grant in which a user authorizes a device through a separate interaction. CIBA is a backchannel authentication flow in which the client identifies a user to authenticate.

DTR lets the authorization server defer a token response within an opted-in grant flow. It does not require a particular user-interaction pattern: a request may wait for the user, a separate reviewer, or an internal process.

See the decision happen

Start with fraud review: approve a transfer as the user, then decide its outcome as the reviewer. Watch the client receive its token.