JetBrains Space EAP Help

Refresh Token Flow

The refresh token flow can be used by desktop or mobile apps, server-side web apps and service accounts. The client should be able to store the refresh token to access Space resources even when the end-user is not online.

The client should be registered with Space as Server-side Web App, Mobile or Desktop App or Service Account.

Prior to making a refresh request, the client application should have obtained a refresh_token from Space. Space supports issuing refresh tokens for the Authorization Code Flow and Resource Owner Password Credentials Flow authorization flows.

Refreshing an access token

The client 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:

ParameterDescription
grant_typeSpecifies the grant type in an OAuth 2.0 request. Required. Set value to refresh_token.
refresh_tokenRequired. The refresh token issued to the client
scope

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):

<SCOPE> ::= <ALL> | <TOKEN_LIST> <ALL> ::= '**' <TOKEN_LIST> ::= <TOKEN> (' ' <TOKEN>)* <TOKEN> ::= <GLOBAL_PERMISSIONS_TOKEN> | <ENTITY_PERMISSIONS_TOKEN> <GLOBAL_PERMISSIONS_TOKEN> ::= <PERMISSIONS> <ENTITY_PERMISSIONS_TOKEN> ::= <ENTITY> ':' <PERMISSIONS> <ENTITY> ::= 'Team' | 'Project' | 'Profile' | 'etc.' <PERMISSIONS> ::= <ALL_PERMISSIONS> | <PERMISSION_LIST> <ALL_PERMISSIONS> ::= '*' <PERMISSION_LIST> ::= <PERMISSION> (',' <PERMISSION>)*

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

Example:

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 client in Space.

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 Space server as described in RFC 6749.

The client 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: mycompany.jetbrains.space Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW Content-Type: application/x-www-form-urlencoded grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA

Space will:

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

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

  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 client 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 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

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

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). Space 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 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 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 Space.

  • 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" }
Last modified: 18 November 2020