JetBrains Space Help

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

  1. Open the API Playground.

  2. Find and select the required endpoint. The required permissions will be shown on the top of the page:

    Check rights in API Playground

    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 as Project.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:

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:

val space = SpaceClient( ktorClient = ktorClientForSpace(CIO), appInstance = SpaceAppInstance(clientId, clientSecret, "https://mycompany.jetbrains.space"), auth = SpaceAuth.ClientCredentials() ) suspend fun requestPermissions(){ space.applications.authorizations.authorizedRights.requestRights( application = ApplicationIdentifier.Me, // project context contextIdentifier = ProjectPermissionContextIdentifier(ProjectIdentifier.Key("MY-PRJ")), // required permissions rightCodes = listOf(PermissionIdentifier.ViewAutomationJobs, PermissionIdentifier.ViewCodeReviews) ) space.applications.authorizations.authorizedRights.requestRights( application = ApplicationIdentifier.Me, // global context contextIdentifier = GlobalPermissionContextIdentifier, rightCodes = listOf(PermissionIdentifier.CreateIssues) ) }
PATCH https://mycompany.jetbrains.space/api/http/applications/me/authorizations/authorized-rights/request-rights Authorization: Bearer here-goes-auth-token Accept: application/json Content-Type: application/json { "contextIdentifier": "project:key:MY-APP", "rightCodes": [ "Automation.Execution.View", "Project.CodeReview.View" ] } PATCH https://mycompany.jetbrains.space/api/http/applications/me/authorizations/authorized-rights/request-rights Authorization: Bearer here-goes-auth-token Accept: application/json Content-Type: application/json { "contextIdentifier": "global", "rightCodes": [ "Project.Issues.Create" ] }

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

  1. On the Extensions | Installed to organization page, find and open the application.

  2. Open the Authorization tab.

  3. Under Global Authorization, click Configure.

  4. In the Requested Permissions window, specify global rights required by the application.

  5. Wait until the permission request is approved by a System Admin. Until that, the specified permissions will be in the Requested state.

    App permissions request

To request context permissions for the application

  1. On the Extensions | Installed to organization page, open the application.

  2. Open the Authorization tab.

  3. If you want the application to have the same set of permissions for all contexts (channels and projects):

    1. Under In-context Authorization, click Configure requirements.

    2. In the Required Permissions window, specify permissions required by the application and click Save and request.

    3. Under In-context Authorization, click Add permission Authorize in new context.

    4. In the Authorize in New Context window, add the required channel and/or project and click Authorize.

  4. If you want the application to have different sets of permissions depending on context (a specific channel or a project):

    1. Under In-context Authorization, click Add permission Authorize in new context.

    2. In the Authorize in New Context window, add the required channel and/or project and click Authorize.

    3. Click Configure and specify permissions required by the application.

    4. Click Save.

  5. 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.

    App context permissions request

Obtain permissions with a permanent application token

The workflow looks as follows:

  1. An application owner registers the application in Space.

  2. The owner manually requests the required permissions on the application's Authorization tab.

  3. A Space user with an appropriate administrator role approves the request.

  4. The owner creates a permanent token on the application's Permanent Tokens tab.

  5. 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:

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:

  1. A Space user interacts with the application performing an action that requires authorization in Space.

  2. 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):

val authUrl = with(URLBuilder("https://mycompany.jetbrains.space/oauth/auth")) { parameters.apply { append("response_type", "code") append("redirect_uri", "https://myapp.url/space") append("client_id", "here-goes-app-clientid") append("request_credentials", "default") // permissions must be separated by whitespace append("scope", "project:key:MY-APP:Project.View project:key:MY-APP:VcsRepository.Read") } build() }

The permissions must be listed in the scope parameter of the initial authentication request.

GET https://mycompany.jetbrains.space/oauth/auth?response_type=code& redirect_uri=https%3A%2F%2Fmyapp.url%2Fspace&client_id=here-goes-app-clientid& request_credentials=default& scope=project%3Akey%3AMY-APP%3AProject.View+project%3Akey%3AMY-APP%3AVcsRepository.Read

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.Create

  • project:key:<project_key> or project:<project_id> for project permissions. For example:

    project:key:MY-APP:Project.Issues.Create project:42P9E54DAkJW:Project.Issues.Create

  • channel:<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:

  1. A user clicks a custom menu item associated with the application.

  2. Space sends a MenuActionPayload request to the application endpoint.

  3. 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 more

  4. The user is shown a dialog in Space asking to authorize the application.

See the full example of the application.

Obtain permissions with a permanent user token

The workflow looks as follows:

  1. A user creates a personal token. When creating the token, the user specifies the required permissions.

  2. 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.

    Spacebox. Request for permissions

  • 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.

    Channel permissions request

  1. Open the corresponding channel and click View request in the message.

  2. Check and approve the requested permissions using the corresponding Approve buttons. To approve all permissions at once, click Approve all.

    Approve permissions request
Last modified: 04 August 2023
Offline Validation of Access Tokens Verify Requests from Space