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
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.
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:
| 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 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 |
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.
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
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 HTTP API Playground.
Find and select the required endpoint. The required rights will be shown on the top of the page:
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
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.
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
On the Applications page, open application's settings.
Open the Endpoint tab.
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.
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:
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.