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 certain 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 a format different from what you see, for example, on the role's Permissions tab. Your application must use this format when requesting permissions from Space programmatically. 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.

Document permissions

Document permissions define what the application is allowed to do within a particular document. For example, update or delete the document. Note that documents include text documents, blog post drafts, checklists, and files.

There are two types of documents in Space:

Applications and other users can only request permissions.

Document folder permissions

Document folder permissions specify what the application is allowed to do within a particular document folder. For example, create new documents, delete documents, and so on.

There are two types of document folders in Space:

Applications and other users can only request permissions.

Request permissions on behalf of an application

There are several ways for an application to get permissions on behalf of itself:

Request permissions in 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 Automation.Execution.View and Project.CodeReview.View permissions for a project with the MY-APP key:

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, contextIdentifier = ProjectPermissionContextIdentifier(ProjectIdentifier.Key("MY-APP")), rightCodes = listOf("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": "project:key:MY-APP", "rightCodes": [ "Automation.Execution.View", "Project.CodeReview.View" ] }

After the application requests the permissions, the request must be approved by an organizaion, project, or channel administrator.

Request permissions on the application's page in Space

To request global permissions for the application

  1. On the Applications 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 Applications 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):

    • 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 Add permission Authorize in new context.

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

    • Under In-context Authorization, click Add permission 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.

  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, Authorization code flow with refresh token, or Implicit flow, 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.

  • document:<document_id> and folder:<document_folder_id> for document and document folder permissions. For example, document:53Q0F54DBlSA:Documents.View, folder:34W1G33FGzAS:DocumentFolders.Create.

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. See the example:

    fun Routing.routes() { post("api/myapp") { // processPayload is a helper function that processes payload from Space // KtorRequestAdapter is an instance of RequestAdapter // it is used to read text and headers from the incoming requests // // ktorClient is the base HTTP client that will be used by the application // to make all requests to Space // // AppInstanceStorage is an instance of SpaceAppInstanceStorage that stores // data on application's client ID, secret, and URL of the Space instance Space.processPayload(KtorRequestAdapter(call), ktorClient, AppInstanceStorage) { payload -> when (payload) { // ... is MenuActionPayload -> { // the payload contains user clientId val result = reactToMenuItem(payload) SpaceHttpResponse.RespondWithResult(result) } // ... } } } } suspend fun ProcessingScope.reactToMenuItem(payload: MenuActionPayload): AppUserActionExecutionResult { // Check if we already have a token for this particular user for this app instance // If not, make permissionRequest to Space // // the implementation of findRefreshTokenData may vary depending on how you want to store token data val refreshTokenAndScope = findRefreshTokenData(payload.clientId, payload.userId) ?: return permissionsRequest // If we have a valid token, make requests to Space. // If the token is invalid, make permissionRequest to Space. val client = clientWithRefreshToken(refreshTokenAndScope.refreshToken, refreshTokenAndScope.scope) return try { doSomethingInSpace(client, payload) AppUserActionExecutionResult.Success(null) } catch (e: PermissionDeniedException) { permissionsRequest } catch (e: RefreshTokenRevokedException) { permissionsRequest } } // the AppUserActionExecutionResult class lists possible application responses // AuthCodeFlowRequired is an app response that requests required permissions private val permissionsRequest = AppUserActionExecutionResult.AuthCodeFlowRequired( listOf( // e.g., the app requires global permissions to create, view, and edit issues AuthCodeFlowPermissionsRequest( // scope contains the list of required permissions // permissions must be separated by whitespace scope = "global:Project.Issues.Create global:Project.Issues.View global:Project.Issues.Edit", // purpose is the string shown to the user in the permission request dialog purpose = "create task sub-items" ) ) )
  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 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.

    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: 12 August 2022