Request Permissions
To access particular Space endpoints, an application must first obtain the corresponding permissions. For example, if your application creates project issues, it must have the Create issues permission. To view issue details, the View issues permission is required, and so on. The whole set of permissions required by the application is called permission scope.
The way an application requests permissions is different for applications acting on behalf of themselves and applications acting on behalf of Space users.
To find out what permissions are required for a particular HTTP API call
Open the API Playground.
Find and select the required endpoint. The required permissions will be shown on the top of the page:
Note that the API Playground shows required permissions in the string format that your application can use in its requests to Space. For example, the Create issues permission must be requested as
Project.Issues.Create
, View issues asProject.Issues.View
, and so on.
Permission context
When requesting a permission, you always specify permission context. For example, the Create issues permission granted in the global context allows creating issues in any project within the entire organization. The same permission granted in the context of a project allows creating issues only in this particular project.
- Global permissions
These are permissions granted in the global (organization) context. 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. Applications and users with other roles can only request global permissions from the system administrators.
- Project permissions
Project permissions define 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. Applications and users with other roles can only request permissions from the project administrators.
- Chat-channel permissions
Chat-channel permissions define 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. Applications and other users can only request permissions from the channel administrators.
Request permissions on behalf of an application
There are several ways for an application to get permissions on behalf of itself:
The application sends a
Request Rights
request to Space. Relevant for: multi-org applications.The application owner (the user who installed the application) requests permissions on the application's page in Space. Relevant for: single-org applications or for testing the applications that are still in development.
The application owner issues a permanent application token. Relevant for: testing the applications that are still in development. Not recommended due to security considerations.
Request permissions with a request to Space
To request a permission, the application must send a request to the request-rights
HTTP API endpoint. For example, this is how the application can request the Automation.Execution.View
and Project.CodeReview.View
permissions for a project with the MY-APP
key and the global Project.Issues.Create
permission:
After the application requests the permissions, the request must be approved by an organization, project, or channel administrator.
Request permissions on the application's page in Space
To request global permissions for the application
On the Extensions | Installed to organization page, find and 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 Extensions | Installed to organization 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.
Obtain permissions with a permanent application token
The workflow looks as follows:
An application owner registers the application in Space.
The owner manually requests the required permissions on the application's Authorization tab.
A Space user with an appropriate administrator role approves the request.
The owner creates a permanent token on the application's Permanent Tokens tab.
The application uses the token to make requests on behalf of itself.
Request permissions on behalf of a user
There are several ways for an application to get permissions on behalf of a user:
The application requests permissions using OAuth scope. Relevant for: applications that authorize using the OAuth 2.0 flow.
The application requests permissions in a response to a MenuActionPayload request. Relevant for: applications which extend menus with custom items.
A Space user issues a permanent user token. Relevant for: testing applications that are still in development. Not recommended due to security considerations.
Request permissions using OAuth scope
If your application uses Authorization code flow or Authorization code flow with refresh token, it must specify the required permissions when obtaining the authorization token from Space.
For a user, the workflow looks as follows:
A Space user interacts with the application performing an action that requires authorization in Space.
The application redirects the user to the Space webpage where they grant the requested permissions to the application.
For example, this is how an application can request permissions to read Git repositories, and view details in the project with the MY-APP
key (Authorization code flow, a user is redirected to https://myapp.url/space
):
The permissions must be listed in the scope
parameter of the initial authentication request.
Note that if a user doesn't grant all requested permissions, the scope included in the request will not match the scope included in the response.
- Permission scope format
Use the following string format for the permission scope:
<context>:<permission>
.The
<context>
is a permission context:global
for global permissions. For example:global:Project.Issues.Create global:Profile.Createproject:key:<project_key>
orproject:<project_id>
for project permissions. For example:project:key:MY-APP:Project.Issues.Create project:42P9E54DAkJW:Project.Issues.Createchannel:<channel_id>
for channel permissions. For example:channel:42P9E54DAkJW:Channel.ViewMessages
To request all available permissions, use the
**
scope.To get the list of all possible permissions, you can use the Get all authorized rights API method.
Request permissions in response to MenuAction payload
If your application extends Space menus with custom items, it can request user authorization right in the Space UI. The workflow looks as follows:
A user clicks a custom menu item associated with the application.
Space sends a
MenuActionPayload
request to the application endpoint.The application checks whether it already has a user token with required permissions. If not, it can send a response to Space requesting the required permissions from the user. The permissions are specified in the
AuthCodeFlowPermissionsRequest.scope
property. Learn moreThe user is shown a dialog in Space asking to authorize the application.
Obtain permissions with a permanent user token
The workflow looks as follows:
A user creates a personal token. When creating the token, the user specifies the required permissions.
The application uses the token to make requests on behalf of the user.
Approve permission requests
Once the application owner requests a permission for the application, Space sends a notification message. The recipient 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 private 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.