JetBrains Space Help

Authorize in Space

Space security is based on access tokens: secrets that are used for authenticating API requests. To communicate with Space, an application must first get an access token. Then it can use this token to send requests to Space. For example:

GET https://mycompany.jetbrains.space/api/http/absences Authorization: Bearer <here-goes-access-token> Accept: application/json

The access token not only authenticates the application in Space (confirms that the application is registered in the system) but also authorizes it (defines what the application is allowed to do in the system).

Authorization subject

When calling the Space API, an application can act either on its own behalf, or on behalf of a Space user. When acting on its own behalf, it is restricted by permissions granted to the application by the Space administrator. When acting on behalf of a user, it is restricted by permissions granted to the application by the user. Users can only grant permissions that they have by themselves.

For example, a chatbot typically posts messages on behalf of itself: in a chat channel, you see this application as the message author. An application which creates an Issue in Space as a result of a user action in some third-party system, may act on behalf of that user. Though, the application creates the issue, the issue author is a particular Space user.

The methods of getting an access token are different depending on the subject. See the On behalf of column in the table below.

Get an access token

To get an access token, your application should use one of the authorization methods supported by Space: one of the OAuth 2.0 authorization flows or authorization with a permanent token. See details below.

Method

Best for

On behalf of

Details

Permanent token

Not recommended

You can use it for testing applications that are still in development

User or application

Unlike OAuth 2.0 flows where the application obtains a temporary token for each communication session, a permanent token never expires. This makes this authorization method less secure though easier to implement.

OAuth 2.0. Authorization Code flow

Web applications with authorization logic on the server

User

The application sends a user to Space via a link that also includes the scope of required resources. After the user logs in to Space, Space redirects the user back to the application using the specified redirect URI. The redirect also contains an authorization code. The application uses the authorization code to obtain an access token from Space.

In Space, the Authorization code flow is used in conjunction with the Refresh code flow. The application gets not only an access token but also a refresh_token. This token lets the application automatically get a new access token once the lifetime of the current one expires.

OAuth 2.0. Client Credentials flow

Applications that need to access resources on behalf of themselves, for example, chatbots.

Application

The application receives an access token from Space by sending it client_id and client_secret.

Resources that require user authorization cannot be accessed using the Client Credentials flow. Use other flows that allow your script to act on behalf of the user.

OAuth 2.0. Implicit flow

Rich client web applications with authorization logic in a browser

User

Deprecated.

The application sends a user to Space via a link that also includes the scope of user account permissions. After the user logs in to Space, Space redirects the user back to the application using the specified redirect URI. The redirect contains an access token for the application.

OAuth 2.0. Resource Owner Password Credentials flow

Not recommended

Potentially, you can use it for scripts that need to access resources on behalf of a user

User

A user provides the application their Space user credentials and the application uses them to get full access to Space on behalf of the user. We do not recommend that you use this flow as it is not secure.

You don't have to explicitly enable this flow as it is enabled by default for all registered applications.

OAuth 2.0 endpoints

Space's OAuth 2.0 endpoints:

Endpoint

URL

Authentication

<Space service URL>/oauth/auth

Token

<Space service URL>/oauth/token

How to implement authorization in your application

If you create your application on top of the Space SDK, you can use the SpaceHttpClient class and its extension methods to implement a particular authorization method.

If you don't use the Space SDK, you can follow the generic instructions provided in this documentation.

Authorization Playground

You can experiment with different authorization ways in the Space Authorization Playground.

Authorization Playground

To open Authoriztion Playground

  1. Enable the Extensions page: On the navigation bar, click ... to expand the menu and choose Extensions.

  2. On the navigation bar, click API PlaygroundExtensions and then select Authorization Playground.

Last modified: 06 December 2022