Resource Owner Password Credentials Flow

Basics

Authorization on behalf of a Space user.
Suitable for an application that accesses resources on behalf of a user (resource owner) which credentials the application knows. The application can be, for example, a device operating system or a highly privileged application.
Typically, the application obtains the user's Space credentials – username and password, via an interactive form. The application then uses these credentials to get full access to Space on behalf of the user.
For more details on the flow, refer to Resource owner password credentials flow specification.

How to implement

Request

To obtain an access token from Space, the application should make a request to the token endpoint <Space service URL>/oauth/token.

Add the following parameters to the HTTP header of the request:

client_id: Required. The ID assigned to your client application when you register it in Space. To get the client ID, go to Administration → Applications and choose your application from the list.
client_secret: Required. The private identifier assigned to your client application when you register it in Space. To get the client secret, go to Administration → Applications and choose your application from the list.

Add the following parameters to the entity-body of the HTTP request in the application/x-www-form-urlencoded format with UTF-8 character encoding:

grant_type

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

username

Required. The resource owner username.

password

Required. The resource owner password.

scope

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

Learn more about permission scope format.

access_type

Indicates whether the application requires access to Space when the user is not online. Allowed values: online (used by default) and offline. If the application requires refreshing access tokens when the user is not online, use the offline value. In this case Space issues a refresh token for the application the first time it exchanges an authorization code for a user. Refer to the Refresh Token page for more information.

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 application 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=password&scope=**&username=user_example&password=password_example&access_type=offline

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

Response

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

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 application 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 application, or is otherwise malformed.
invalid_client — Application authentication failed (e.g., unknown application, no application 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 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.

error_description

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

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.

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 May 2023