JetBrains Space Help

Register Application in Space

Before you can start using an application, you must register it in your Space instance. Among other things, during the registration, Space issues authentication credentials for the application, and saves application's endpoint required for the two-way communication with the app.

Step 1. Add the application

  1. On the navigation bar, click administration.png Administration and choose Applications.

  2. Click New application.

  3. Give your application a unique name and click Create. Now, you should specify other application settings.

Step 2. Choose an authentication/authorization flow

Decide how your application must authenticate and authorize itself in Space. Authentication and authorization flow depends on the application type:

FlowsBest forOn behalf ofDetails
Client Credentials flowApplications 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.

Implicit flowRich client web applications with authorization logic in a browserUserThe 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.
Authorization Code flowWeb applications with authorization logic on the serverUserThe 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.
Resource Owner Password Credentials flow

Not recommended

Potentially, you can use it for scripts that need to access resources on behalf of some 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.

Refresh Token flowDesktop or mobile applications that request authorization tokens non-interactivelyUser

This is not a separate flow but an extension for Resource Owner Password Credentials and Authorization Code flows. If you select one of these flows during application registration, the Refresh Token flow will be automatically enabled for the application.

In this 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.

To select a flow

  1. On the Applications page, open application's settings.

  2. Open the Authentication tab. When you register the application, Space automatically creates a separate service account for it. The application should use this account to obtain an access token from Space. In Application credentials:

    • Client ID is an OAuth counterpart of "username".

    • Client secret is an OAuth counterpart of "password".

  3. Enable one of the flows with the corresponding checkbox:

    • Client Credentials Flow

    • Authorization Code Flow. In Redirect URIs, specify URI(s) where Space will redirect users after logging in Space.

    • Implicit Flow. In Redirect URIs, specify URI(s) where Space will redirect users after logging in Space.

  4. There are two more flows that do not require explicit enabling in Space:

    • Resource Owner Password Credentials Flow – this flow is always enabled.

    • Refresh Token Flow – this flow is enabled automatically once you select Authorization Code Flow or Resource Owner Password Credentials Flow.

Step 3. Specify application rights

Specify what rights your client needs to access specific Space resources. Note that there are two types of rights:

  • Global: These are permissions granted on the global (organization) level. For example, if you grant your application Add new members, it will be allowed to add new Space members within the entire organization.

  • Project-level: These are permissions granted for a specific project. For a project-level permission, you must also specify a project where this permission is granted (see Step 4. Authorize the application in projects). For example, it is not enough to grant the app the Project Issues | View issues right – you should also specify the project where the app will be allowed to view issues.

    On the Requested rights tab, project-level rights are grouped into the following categories:

    • Project

    • Project Checklists

    • Project Issues

    • Project Boards

    • Project Responsibilities

To specify application rights

  1. On the Applications page, open application's settings.

  2. Open the Requested rights tab and select the required rights from the list.

  3. If you don't have the rights you've selected for your application, you will need to have them authorized by a Space user that has them. Until that, these rights will have the pending status and won't be available to your application.

  4. To authorize requested rights, one should:

    • On the navigation bar, click administration.png Administration and choose Applications.

    • Choose the application from the list.

    • On the sidebar, click Authorization.

    • The pending requested rights will be listed here. Click Authorize to grant a right to the app.

To find out what rights are required for a certain HTTP API call

  1. Open the API Playground.

  2. Find and select the required endpoint. The required rights will be shown on the top of the page:

    Check rights in API Playground

Step 4. Authorize the application in projects

If your application is supposed to retrieve data about particular projects (say, view the list of project issues, or manage project checklists), you must first grant the application the required project rights, and then, authorize the application in the required project.

To authorize the application in projects

  1. On the Applications page, open application's settings.

  2. Open the Authorization tab and click Add project.

  3. In the opened window, in Select projects, select one or more projects.

  4. Below the projects list, choose the project-level rights that will be granted to the application in the context of the selected projects (The project-level rights you see here contains the rights that were granted on the Requested rights tab).

  5. After this, the requested project rights need to be authorized by the project administrator. Unit that, they will have the Pending status.

  6. To authorize requested rights, one should:

    • On the navigation bar, click administration.png Administration and choose Applications.

    • Choose the application from the list.

    • On the sidebar, click Authorization.

    • The pending requested rights will be listed here. Click Authorize to grant a right to the app.

Step 5. Specify the application's endpoint

If your application provides two-way communication with Space (for example, it's a chatbot, or a custom menu), you must register application's endpoint. Space will use this endpoint to send requests to your application.

When receiving requests from Space, your application should verify the Space instance using the verification token or the signing key method. Learn more

To specify the endpoint

  1. On the Applications page, open application's settings.

  2. Open the Endpoint tab.

  3. To generate a signing key or a verification token, click Generate under Signing key or Verification token. Note that you should implement one of this verification methods in your application.

  4. In Endpoint URI, specify a URI of the endpoint your application uses to handle incoming requests.

Step 6. Add SSH Keys

If your application will access Space Git repositories via SSH (for example, your app is an external CI/CD server), you should provide the application's SSH public key.

To add an SSH key:

  1. On the Applications page, open application's settings.

  2. Open the SSH Keys tab.

  3. Click Add SSH key and either paste the key into the Key field or upload the file containing the key using the field below.

  4. Click Add.

Last modified: 27 July 2021