Register Application in Space

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 `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 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 is an OAuth counterpart of "username".
- Client secret is an OAuth counterpart of "password".
(Optional) To enable the client credentials flow, in OAuth2 flows on behalf of the Application, select Enable client credentials flow.

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.
(Optional) To enable the authorization code flow, in OAuth 2 flows on behalf of users, select Enable code flow. In Redirect URIs specify URI(s) where Space will redirect users after logging in 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) 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 enabled by default.
- 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 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:

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.