Authorization Code Flow

The authorization code flow is best used for web application with a confidential client running on a server side.

Resource owners access the client via an HTML user interface rendered in a user-agent on the device used by the resource owner.

The client credentials as well as any access token issued to the client are stored on the web server and are not exposed to or accessible by the resource owner.

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

Initial request

To start the authentication process, the client should redirect the user's browser to the authentication endpoint <Space service URL>/oauth/auth in the following format:

        
            ${Space Service URL}/oauth/auth?response_type=code&state=${State}&redirect_uri=${Client redirect URI}&request_credentials=${Request credentials mode}&client_id=${Client ID}&scope=${Scope}&access_type={online|offline}

For example:

        
            https://mycompany.jetbrains.space/oauth/auth?response_type=code&state=9b8fdea0-fc3a-410c-9577-5dee1ae028da&redirect_uri=https%3A%2F%2Fmyservice.company.com%2Fauthorized&request_credentials=skip&client_id=98071167-004c-4ddf-ba37-5d4599fdf319&scope=0-0-0-0-0%2098071167-004c-4ddf-ba37-5d4599fdf319

To instruct Space to issue a refresh token, add the access_type=offline parameter to your request:

            
            https://mycompany.jetbrains.space/oauth/auth?response_type=code&state=${State}&redirect_uri=${Client redirect URI}&request_credentials=${Request credentials mode}&client_id=${Client ID}&scope=${Scope}&access_type=offline

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

Parameter	Description
`response_type`	Specifies the grant type in an OAuth 2.0 request. Set value to `code`.
`state`	An identifier for the current application state. For example, it can be a key for a local storage object that contains information about the location of the current user in the client application.
`redirect_uri`	A URI in your client application that can handle responses from Space.
`request_credentials`	A parameter that determines whether the user should be asked to log in. The following values are valid: `skip`— use when the client application allows anonymous access. If the user is already logged in to Space, the user is granted access to the client application. If the user is not logged in to Space and the guest account is not banned, the user is granted access to the client application as a guest. If the user is not logged in to Space and the guest account is banned, the user is redirected to the login page. `silent`— same as `skip`, but redirects the user to the client application in all cases. If the guest account is banned, the user is redirected to the client application with an authentication error. `required`— logs the user out of Space and redirects them to the login page. Use as a response to a logout request in the client application. `default`— use when the client application does not allow anonymous access. If the user is already logged in to Space, the user is granted access to the client application. If the user is not logged in to Space, the user is redirected to the login page.
`client_id`	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 client from the list.
`client_secret`	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 client from the list.
`scope`	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.
`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.

Handling response

If the resource owner grants the access, Space issues an authorization code and delivers it to the client by adding the following parameters to the query component of the redirection URI using the application/x-www-form-urlencoded format:

Parameter	Description
code	The authorization code generated by Space. The authorization code will expire shortly after it is issued to mitigate the risk of leaks. The client must not use the authorization code more than once. If an authorization code is used more than once, Space will deny the request. The authorization code is bound to the client identifier and redirection URI.
state	The exact value received from the client in the authorization request.

Example: Space redirects the browser by sending the following HTTP response:

            
            HTTP/1.1 302 Found
            Location: https://myservice.company.com/authorized?code=SplxlOBeZQQYbYS6WxSbIA&state=xyz

The client must ignore unrecognized response parameters.

Handling error response

If the resource owner denies the access request or if the request fails for reasons other than a missing or invalid redirection URI, Space informs the client by adding the following parameters to the query component of the redirection URI using the application/x-www-form-urlencoded format:

error

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

invalid_request— The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
unauthorized_client— The client is not authorized to request an authorization code using this method.
access_denied— The resource owner or Space denied the request.
unsupported_response_type— Space does not support obtaining an authorization code using this method.
invalid_scope— The requested scope is invalid, unknown, or malformed.

error_description

Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding what went wrong.

Exchanging authorization code for an access token

After the client receives the code it can exchange it for an access token.

The client makes a request to the Space token endpoint by sending the following parameters using the application/x-www-form-urlencoded format with a character encoding of UTF-8 in the HTTP request entity-body:

            POST /oauth/token
            Host: ${Space Service URL}
            Accept: application/json
            Authorization: Basic ${base64(${Client ID} + ":" + ${Client secret})}
            Content-Type: application/x-www-form-urlencoded

            grant_type=authorization_code&code=${Code received on a previous step}&redirect_uri=${Client redirect URI}
        

Example:

            POST /oauth/token
            Host: Space.company.com
            Accept: application/json
            Authorization: Basic OTgwNzExNjctMDA0Yy00ZGRmLWJhMzctNWQ0NTk5ZmRmMzE5OmVBVXlLZ1ZmaFNiVg0K
            Content-Type: application/x-www-form-urlencoded

            grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=https%3A%2F%2Fmyservice.company.com%2Fauthorized
        

Handling Access Token Response

If the access token request is valid and authorized, Space issues an access token. If the request has failed or is invalid, the Space server returns an error response.

Example of a successful response:

            HTTP/1.1 200 OK
            Content-Type: application/json;charset=UTF-8

            {
            "access_token":"1443459450185.0-0-0-0-0.98071167-004c-4ddf-ba37-5d4599fdf319.0-0-0-0-0%3B1.MCwCFC%2FYWvLjHdzOdpLleDLITJn4Mz9rAhRklCoZ2dlMkh2aCd1K5QQ89ibsxg%3D%3D
            "expires_in":3600,
            }
        

Last modified: 12 May 2020