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 authentication 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 choose 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.

Granting permissions to the application

To let your application access particular resources in Space, you must grant it the corresponding permissions. There are two types of permissions in Space:

Global permissions

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. Only administrators with the System Admin role can grant global permissions. Users with other roles can only request global permissions from the system administrators.

Context permissions

These are permissions granted in a specific context:

Project-level permissions specify what the application is allowed to do within a particular project. For example, view issues, check out the project repository, and so on. Only users with the Project Admin role (within the required project) can grant a project-level permission. Users with other roles can only request permissions from the project administrators.
(Not yet available) Chat-channel permissions specify what the application is allowed to do within a particular chat channel. For example, post messages, add new members, and so on. Only channel administrators can grant a chat-channel permission. Other users can only request permissions from the channel administrators.

To understand what exact permissions are required for your application, follow the instructions.

To request global permissions for the application

On the Applications page, open the application.
Open the Authorization tab.
Under Global Authorization, click Configure.
In the Requested Permissions window, specify global rights required by the application.
Wait until the permission request is approved by a System Admin. Until that, the specified permissions will be in the Requested state.

To request context permissions for the application

On the Applications page, open the application.
Open the Authorization tab.
If you want the application to have the same set of permissions for all contexts (channels and projects):
- Under In-context Authorization, click Configure requirements.
- In the Required Permissions window, specify permissions required by the application and click Save and request.
- Under In-context Authorization, click Authorize in new context.
- In the Authorize in New Context window, add the required channel and/or project and click Authorize.
If you want the application to have different sets of permissions depending on context (a specific channel or a project):
- Under In-context Authorization, click Authorize in new context.
- In the Authorize in New Context window, add the required channel and/or project and click Authorize.
- Click Configure and specify permissions required by the application.
- Click Save.
Wait until the permission request is approved by a channel or a project administrator. Until that, the specified permissions will be in the Requested state.

To approve a permission request

Once a user requests a permission for an application, Space sends a notification message. The recepient of the message depends on the context:
- For global permissions: the Spacebox channel of all users with the System Admin role.
- For project permissions: the Spacebox channel of all users with the Project Admin role in this project.
- For chat channel permissions: the channel itself. All channel participants can see the request but only the channel administrator (the user who created the channel) can approve it.
Open the corresponding channel and click View request in the message.
Check and approve the requested permissions using the corresponding Approve buttons. To approve all permissions at once, click Approve all.

To find out what permissions 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:

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: public key, signing key, SSL client certificate, 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 certificate: 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 certificate: 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 Public 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: 13 December 2021