Register Single-Org Applications
Registering an application is the main way to install a single-org application to your Space instance. When registering the application, you manually specify its settings: an authorization flow, required permissions, the application's endpoint, and others.
Add the application to your Space instance
On the main menu, click
Extensions and choose Installed.Click New application.
Specify:
A unique application Name.
An application Email. If the application pushes commits to Space repository, it can use this email in
committerfield. This is required in case the Verify committer option is enabled for the repository.
Click Create.
Now, you should specify other application settings.
Choose an authentication flow
Decide how your application must authenticate and authorize in Space. Learn how to implement authorization in your application.
On the Extensions | Installed to organization 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.
If your application is a static web page that authorizes in Space using the Authorization Code flow, disable the Client Credentials flow. Learn more
Authorization Code Flow. In Redirect URIs, specify URI(s) where Space will redirect users after logging in Space. If you want to use the PKCE extension, choose Require PKCE. If you want to allow applications to initiate the Authorization Code flow without providing the client secret (less secure), choose Allow public (untrusted) clients.
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.
Request application permissions
To access particular resources in Space on behalf of itself, your application requires corresponding permissions. You can request the required permissions on the application's Authorization tab or from the application itself. For more information, refer to Request Permissions.
Specify 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.
On the Extensions | Installed to organization 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.
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.
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.
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.
HTTP authentication: this method is an implementation of the standard HTTP authentication using the
Authenticationrequest header. You should choose one of the two authentication ways:Bearer: Space will send the specified Token in the
Authorizationheader. 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
Authorizationheader. 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.
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.
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.
On the Extensions | Installed to organization 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.
Subscribe to Space events
If you want your application to receive notifications about events in Space, you can do this by using webhooks. Learn more.