OAuth 2.0 Authorization Code Requests and Responses

Jakob Jenkov
Last update: 2014-06-15

The authorization code grant consists of 2 requests and 2 responses in total. An authorization request + response, and a token request + response.

Authorization Request

The authorization request is sent to the authorization endpoint to obtain an authorization code. Here are the parameters used in the request:

response_type Required. Must be set to code
client_id Required. The client identifier as assigned by the authorization server, when the client was registered.
redirect_uri Optional. The redirect URI registered by the client.
scope Optional. The possible scope of the request.
state Optional (recommended). Any client state that needs to be passed on to the client request URI.

Authorization Response

The authorization response contains the authorization code needed to obtain an access token. Here are the parameters included in the response:

code Required. The authorization code.
state Required, if present in request. The same value as sent by the client in the state parameter, if any.

Authorization Error Response

If an error occurs during authorization, two situations can occur.

The first is, that the client is not authenticated or recognized. For instance, a wrong redirect URI was sent in the request. In that case the authorization server must not redirect the resource owner to the redirect URI. Instead it should inform the resource owner of the error.

The second situation is that client is authenticated correctly, but that something else failed. In that case the following error response is sent to the client, included in the redirect URI:

error Required. Must be one of a set of predefined error codes. See the specification for the codes and their meaning.
error_description Optional. A human-readable UTF-8 encoded text describing the error. Intended for a developer, not an end user.
error_uri Optional. A URI pointing to a human-readable web page with information about the error.
state Required, if present in authorization request. The same value as sent in the state parameter in the request.

Token Request

Once an authorization code is obtained, the client can use that code to obtain an access token. Here is the access token request parameters:

client_id Required. The client application's id.
client_secret Required. The client application's client secret .
grant_type Required. Must be set to authorization_code .
code Required. The authorization code received by the authorization server.
redirect_uri Required, if the request URI was included in the authorization request. Must be identical then.

Token Response

The response to the access token request is a JSON string containing the access token plus some more information:

{ "access_token"  : "...",
  "token_type"    : "...",
  "expires_in"    : "...",
  "refresh_token" : "...",

The access_token property is the access token as assigned by the authorization server.

The token_type property is a type of token assigned by the authorization server.

The expires_in property is a number of seconds after which the access token expires, and is no longer valid. Expiration of access tokens is optional.

The refresh_token property contains a refresh token in case the access token can expire. The refresh token is used to obtain a new access token once the one returned in this response is no longer valid.

Jakob Jenkov

Featured Videos

Java ForkJoinPool

P2P Networks Introduction


Java Persistence
Close TOC
All Tutorial Trails
All Trails
Table of contents (TOC) for this tutorial trail
Trail TOC
Table of contents (TOC) for this tutorial
Page TOC
Previous tutorial in this tutorial trail
Next tutorial in this tutorial trail