JetBrains Space Help

Refresh Token Flow


Refreshing an access token

The application makes a refresh request to the token endpoint <Space service URL>/oauth/token by adding the following parameters to the HTTP request entity-body in the application/x-www-form-urlencoded format with UTF-8 character encoding:


Specifies the grant type in an OAuth 2.0 request. Required. Set value to refresh_token.


Required. The refresh token issued to the application.


Required. A space separated list of rights required to access specific resources in Space.

The rights are grouped in four categories: Global, Profile, Team, Project. Use the following syntax to specify the rights (shown here in BNF notation):


Wildcards are accepted. For global rights, category is omitted.


AddNewProfile,AddNewTeam Team:EditTeam Profile:EditAbsences,EditLanguages Project:*

The rights you specify in scope should be first added to the list of requested rights and authorized for your application in Space.

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

The application makes the HTTP request in the following format using transport-layer security:

POST /oauth/token Host: ${Space Service URL} Authorization: Basic ${base64(${Client ID} + ":" + ${Client secret})} Content-Type: application/x-www-form-urlencoded grant_type=refresh_token&refresh_token=${Refresh token received from Space}

Example (with extra line breaks for display purposes only):

POST /oauth/token Host: Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW Content-Type: application/x-www-form-urlencoded grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA

Space will:

  1. Require application authentication for confidential applications or for any application that was issued application credentials (or with other authentication requirements)

  2. Authenticate the application if application authentication is included and ensure that the refresh token was issued to the authenticated application.

  3. Validate the refresh token.

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

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

Error response

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


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 application, or is otherwise malformed.

  • invalid_client— Application authentication failed (e.g., unknown application, no application authentication included, or unsupported authentication method). Space may return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported. If the application attempted to authenticate via the "Authorization" request header field, the Space 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 application.

  • 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 application.

  • unauthorized_client— The authenticated application is not authorized to use this authorization grant type.

  • unsupported_grant_type— The authorization grant type is not supported by Space.

  • invalid_scope— The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.


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


A URI identifying a human-readable web page with information about the error, used to provide the application 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" }
Last modified: 18 August 2021