JetBrains Space EAP Help

Client Credentials Flow

The Client Credentials Flow can be only used by a confidential server-side client that accesses Space on behalf of itself.

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

Request

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

To obtain an access token from Space, the client needs to provide values for the following parameters in authorization requests:

ParameterDescription
grant_typeRequired. Specifies the grant type in an OAuth 2.0 request. Set value to client_credentials.
client_idRequired. The ID assigned to your client application when you register it in Space. To get the client ID, go to administration.png Administration → Applications and choose your client from the list.
client_secretRequired. The private identifier assigned to your client application when you register it in Space. To get the client secret, go to administration.png Administration → Applications and choose your client from the list.
scope

Optional. 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.

The request must contain the "Authorization" header in the following format:

Authorization: Basic <base64(client_id + “:” + client_secret)>

To get a correct value, combine the client_id and client_secret in a single string using semicolon as a delimiter and encode it into Base64 format.

For example, the client makes the following HTTP request using transport-layer security:

POST /oauth/token Host: jetbrains.team Authorization: Basic dmFsaWQtc2VydmljZS1pZDp2YWxpZC1zZXJ2aWNlLXNlY3JldA== Content-Type: application/x-www-form-urlencoded grant_type=client_credentials&scope=**

If the request is valid, Space will authenticate the client.

Response

If the access token request is valid and authorized, Space will issue an access token and optional refresh token. It will construct the response by adding the following parameters to the entity-body of the HTTP response with a 200 (OK) status code:

ParameterDescription
access_tokenThe access token issued by Space.
token_type The type of the token issued by Space. Value is case insensitive.
expires_inThe lifetime in seconds of the access token. For example, the value "3600" denotes that the access token will expire in one hour from the time the response was generated.
scopeOptional, if identical to the scope requested by the client; otherwise, required. A space separated list of rights required to access specific resources in Space.

The parameters are included in the entity-body of the HTTP response using the "application/json" media type. The parameters are serialized into 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.

Space includes the HTTP "Cache-Control" response header field with a value of "no-store" in any response containing tokens, credentials, or other sensitive information, as well as the "Pragma" response header field with a value of "no-cache".

Example:

HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache { "token_type": "Bearer", "expires_in": 600, "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIzNThlMDRlOS1jNDc1LTRkNGUtOGM4OS1lODA3ZTQxNjk3MmMiLCJhdWQiOiIzNThlMDRlOS1jNDc1LTRkNGUtOGM4OS1lODA3ZTQxNjk3MmMiLCJvcmdEb21haW4iOiJqZXRicmFpbnMudGVhbSIsInNjb3BlIjoiKioiLCJuYW1lIjoiTXkgU2VydmljZSIsImlzcyI6Imh0dHBzOi8vamV0YnJhaW5zLnRlYW0iLCJwcmluY2lwYWxfdHlwZSI6IlNFUlZJQ0UiLCJleHAiOjE1NjQ1MDU0MzAsImlhdCI6MTU2NDUwNDgzMH0._1uLmGWUfeG52p4_LcLdZN29at14CGG_RE4KusWY34A", "refresh_token": null, "scope": "**" }

Errors

If the request failed client authentication or is invalid, Space responds with an HTTP 400 (Bad Request) status code (unless specified otherwise) and includes the following parameters with the 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 to assist the client developer in understanding what went wrong.

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: 09 June 2020