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 hardly depends on the application type:
| Application type | Supported flows |
|---|---|
| Server-side Web App | |
| JavaScript Web App | |
| Mobile or Desktop App | |
| Service Account |
To select a flow:
On the Applications page, open application's settings.
Open the Authentications tab. When you register the application, Space automatically creates a separate service account for it. The application can use this account to authenticate Space on behalf of itself. In Application credentials:
Client ID stands for the application's "username".
Client secret stands for the application's "password".
Note that if the app authorizes on behalf of itself, it will have no access to resources that require user consent (for example, publishing an article). To authorize the app on behalf of a user, employ other authentication/authorization flows. See below.
(Optional) To enable the client credentials flow, in OAuth2 flows on behalf of the Application, select Enable client credentials flow.
(Optional) To enable the code flow, in OAuth 2 flows on behalf of users, select Enable code flow. In Redirect URIs specify URI(s) that your client application will use to handle responses from Space.
(Optional) To enable the implicit flow, in OAuth 2 flows on behalf of users, select Enable implicit flow. In Redirect URIs specify URI(s) that your client application will use to handle responses from Space.
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 Authorizations.
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: img src="tutorial.checkRightsInApiPlayground.png" alt="Check rights in API Playground" width="1208"/>
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 Authorizations 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 Authorizations.
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.
To specify the endpoint
On the Applications page, open application's settings.
Open the Endpoint tab.
Use the Generate signing key or Generate verification token button to create either a key or a token. When receiving requests from Space, your application should use the generated key or a token to verify the Space instance.
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.