Refresh Token - Help

Reference to the Standard

Specification for Authorization Code with a Refresh Token Flow (RFC 6749)

Prerequisites

Client is a desktop or mobile application.

The client is registered as a service in Hub. That is, the client "knows" its serviceId and serviceSecret. It should be able to store refreshToken. With refresh token it can access resources server even when end-user is not online.

The client application obtained a refresh_token from Hub. Hub supports issuing refresh tokens for the Authorization Code and Resource Owner Password Credentials authorization flows.

Refreshing an Access Token

If Hub issued a refresh token to the client, the client makes a refresh request to the token endpoint by adding the following parameters using the "application/x-www-form-urlencoded" format with a character encoding of UTF-8 in the HTTP request entity-body:

grant_type

Required. Value must be set to "refresh_token".

refresh_token

Required. The refresh token issued to the client.

scope

Required. The scope of the access request: A space separated list of IDs of the registered in Hub services associated with the resource servers. For example, if the client wants to access issues in YouTrack it should find out the ID of YouTrack service in Hub. The client can access more then one resource server with a single access token.

Note:The requested scope must not include any scope not originally granted by the resource owner, and if omitted is treated as equal to the scope originally granted by the resource owner.

Because refresh tokens are typically long-lasting credentials used to request additional access tokens, the refresh token is bound to the client to which it was issued. If the client type is confidential or the client was issued client credentials (or assigned other authentication requirements), the client must authenticate with the Hub server as described in RFC 6749.

For example, the client makes the following HTTP request using transport-layer security (with extra line breaks for display purposes only):

POST /api/rest/oauth2/token
Host: hub.company.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA

The authorization server (Hub) will:

Require client authentication for confidential clients or for any client that was issued client credentials (or with other authentication requirements)
Authenticate the client if client authentication is included and ensure that the refresh token was issued to the authenticated client.
Validate the refresh token.

If the refresh token is valid and authorized, Hub issues an access token.

If the request failed verification or is invalid, Hub returns an error response.

Along with new access token, Hub may issue a new refresh token, in which case the client must discard the old refresh token and replace it with the new one. The authorization server (Hub) may revoke the old refresh token after issuing a new refresh token to the client. If a new refresh token is issued, the refresh token scope must be identical to that of the refresh token included by the client in the request.

Error Response from Hub for the Access Token Request

error

A single ASCII [USASCII] error code from the following:

invalid_request - The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed.
invalid_client - Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method). The authorization server may return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported. If the client attempted to authenticate via the "Authorization" request header field, the Hub server will respond with an HTTP 401 (Unauthorized) status code and include the "WWW-Authenticate" response header field matching the authentication scheme used by the client.
invalid_grant - The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.
unauthorized_client - The authenticated client is not authorized to use this authorization grant type.
unsupported_grant_type - The authorization grant type is not supported by Hub.
invalid_scope - The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.

error_description

Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred.

error_uri

A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.

The parameters are included in the entity-body of the HTTP response using the "application/json" media type. The parameters are serialized into a JSON structure by adding each parameter at the highest structure level. Parameter names and string values are included as JSON strings. Numerical values are included as JSON numbers. The order of parameters does not matter and can vary.

For example:

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
"error":"invalid_request"
}