Add Application to 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.

Creating an application

On the navigation bar, click Administration and choose Applications.
Click New application.
Give your application a unique name and click Create. Now, you should specify other application settings.

Choosing an authorization flow

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

Flows	Best for	On behalf of	Details
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.
Implicit flow	Rich client web applications with authorization logic in a browser	User	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.
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.
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 flow	Desktop or mobile applications that request authorization tokens non-interactively	User	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

On the Applications page, open application's settings.
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".
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.
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.

Specifying 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 Authorizing 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

On the Applications page, open application's settings.
Open the Requested rights tab and select the required rights from the list.
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.
To authorize requested rights, one should:
- On the navigation bar, click 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

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

Authorizing 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

On the Applications page, open application's settings.
Open the Authorization tab and click Add project.
In the opened window, in Select projects, select one or more projects.
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).
After this, the requested project rights need to be authorized by the project administrator. Unit that, they will have the Pending status.
To authorize requested rights, one should:
- On the navigation bar, click 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.

Specifying an application 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 one of the methods: signing key, verification token, SSL, or HTTP authentication.

To specify the endpoint

On the Applications page, open application's settings.
Open the Endpoint tab.
In Endpoint URL, specify a URL of the endpoint your application uses to handle incoming requests. Note that if your app uses HTTPS, you can additionally select Verify SSL certificates. In this case, Space will check validity of the endpoint's SSL certificate.
Under Authentication, select how your application will authenticate Space:
- Public key: (Recommended) this method requires the application to calculate a request hash and compare it to a hash in the request header. To calculate the hash, the application must first obtain a public key from Space. This is done with an HTTP request.
  Learn how to implement hash calculation with a public key in your application: instructions for Space SDK | general instructions.
- Signing key: this method requires the application to calculate a request hash and compare it to a hash in the request header. To generate a key that will be used for hash calculation, click Generate.
  Learn how to implement hash calculation in your application: instructions for Space SDK | general instructions.
- SSL client key: this method implies that Space will encrypt all requests to the application using an SSL key. Request decrypting is done not by the application but by the web server that hosts the application. To use this method, you must select an SSL keystore that contains the required client key.
  Learn how to verify Space using SSL client key: general instructions.
- Verification token: (Obsolete) this method requires the application to compare the verification token sent in the request header to the saved verification token. To generate a token, click Generate.
  Learn how to check the token in your application: instructions for Space SDK | general instructions.
- HTTP authentication: this method is an implementation of the standard HTTP authentication using the Authentication request header. You should choose one of the two authentication ways:
  - Bearer: Space will send the specified Token in the Authorization header. For example: Authorization: Bearer abc1234. The application must compare the token in the request with the saved token.
  - Basic: Space will send the specified Username and Password in the Authorization header. For example: Authorization: Basic am9obmRvZTpwd2QxMjM0. Space encodes the username and password using the Base64 encoding. Note that this is not encryption: it is just a different data representation. From the point of security, it is equal to sending the username and password as plain text.
  Learn how to verify Space using HTTP authentication: general instructions.
Important notes:
- You can select one or more verification methods.
- You should implement the selected verification methods in your application.
- We recommend Signing key as the most secure verification method.

Adding 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:

On the Applications page, open application's settings.
Open the SSH Keys tab.
Click Add SSH key and either paste the key into the Key field or upload the file containing the key using the field below.
Click Add.

Last modified: 08 October 2021