OAuth2 Refresh Token Request Explained

An OAuth2 refresh token request is used to obtain a new access token when the current access token has expired. (Access tokens can also be refreshed prior to expiration.) Refresh tokens are long-lived credentials that allow an application to request new access tokens without requiring the user to interactively re-authorize the application in a browser. Here's the general format of an OAuth2 refresh token HTTP request:

1. HTTP Method

The refresh token request is typically sent as an HTTP POST request.

2. Endpoint URL

The request is sent to the token endpoint of the OAuth2 authorization server. The token endpoint URL is provided by the OAuth2 service (e.g., "https://oauth2.example.com/token").

3. Headers

The request must include the following headers:

Content-Type

Specifies the format of the request body.

For OAuth2 refresh token requests, this is usually:

Content-Type: application/x-www-form-urlencoded

Authorization (optional, depending on the OAuth2 provider)

If the client is confidential (e.g., a web server application), the request may need to include client authentication.
This is typically done using HTTP Basic Authentication, where the "client_id" and "client_secret" are encoded in the "Authorization" header:
```
Authorization: Basic base64(client_id:client_secret)
  
```

4. Request Body

The request body is sent as URL-encoded key-value pairs ("application/x-www-form-urlencoded"). It includes the following parameters:

Required Parameters

Parameter	Description
`grant_type`	Must be set to `refresh_token`.
`refresh_token`	The refresh token previously issued by the authorization server.
`client_id`	The client identifier (if not provided in the `Authorization` header).
`client_secret`	The client secret (if not provided in the `Authorization` header).

Optional Parameters

Parameter	Description
`scope`	(Optional) A space-separated list of scopes to request for the new access token. If omitted, the new access token will have the same scopes as the original access token.

5. Example Request

Here’s an example of an OAuth2 refresh token request:

Request URL

POST https://oauth2.example.com/token

Headers

Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)

Request Body

grant_type=refresh_token
&refresh_token=abc123def456ghi789jkl012mno345pqr678stu901
&client_id=your_client_id
&client_secret=your_client_secret
&scope=read write

6. Response

If the request is successful, the authorization server responds with a JSON object containing the new access token and optionally a new refresh token.

Example Response

{
"access_token": "new_access_token_here",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "new_refresh_token_here",  // Optional, may not always be returned
"scope": "read write"
}

Response Fields

Field	Description
`access_token`	The new access token.
`token_type`	The type of token (usually `Bearer`).
`expires_in`	The lifetime of the access token in seconds.
`refresh_token`	(Optional) A new refresh token, if the authorization server issues one.
`scope`	(Optional) The scopes associated with the new access token.

7. Error Handling

If the request fails, the authorization server returns an error response in JSON format. Common errors include:

Example Error Response

{
"error": "invalid_grant",
"error_description": "The refresh token is invalid or expired."
}

Common Error Codes

Error Code	Description
`invalid_grant`	The refresh token is invalid, expired, or revoked.
`invalid_client`	Client authentication failed (e.g., invalid `client_id` or `client_secret`).
`invalid_request`	The request is missing required parameters or is malformed.
`unauthorized_client`	The client is not authorized to use the refresh token grant type.

Summary

The general format of an OAuth2 refresh token HTTP request includes:

HTTP Method: "POST"
Endpoint: Token endpoint URL
Headers: "Content-Type: application/x-www-form-urlencoded" and optionally "Authorization: Basic base64(client_id:client_secret)"
Body: URL-encoded key-value pairs with "grant_type=refresh_token", "refresh_token", and other required/optional parameters.
Response: A JSON object containing the new access token and optionally a new refresh token.

This process allows your application to maintain access to protected resources without requiring the user to re-authenticate.