Confluence Space Permission Transition API

openapi: 3.2.0
info:
  title: Confluence Cloud REST API v2 Space Permission Transition API
  description: This document describes Confluence's v2 APIs. This is intended to be an iteration on the existing Confluence Cloud REST API with improvements in both endpoint definitions and performance.
  termsOfService: https://developer.atlassian.com/platform/marketplace/atlassian-developer-terms/
  version: 2.0.0
servers:
- url: https://{your-domain}/wiki/api/v2
  variables:
    your-domain:
      default: no-default
      description: Specific domain of the Confluence site being used. Must be provided.
tags:
- name: Space Permission Transition
  description: ''
paths:
  /space-permissions/transition/combinations:
    get:
      tags:
      - Space Permission Transition
      operationId: listSpacePermissionCombinations
      summary: List unassigned space permission combinations
      description: 'Lists the unique unassigned space permission combinations currently present on the tenant.

        Combinations that already map to a space role are filtered out server-side. Each row carries

        the decoded set of space permissions and the principal types that currently hold the

        combination — these inform which `principalType` values are valid to include in the matching

        bulk role-assignments request.


        Results are always sorted by `principalCount` descending. Sort field and sort order are not

        configurable; page size is controlled by the `limit` query parameter (default 25, min 1,

        max 250). Use the `cursor` field to page through additional results. The `generatedAt` field

        reflects the last audit run that populated the combinations table — call the

        generate-combinations endpoint to refresh stale data.


        **Permissions required**:

        User must be a Confluence administrator.'
      parameters:
      - name: cursor
        in: query
        required: false
        description: Opaque cursor returned from a previous page in the `cursor` field of the response. Omit for the first page.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: The maximum number of combinations to return per page. Requests outside the supported range return `400`.
        schema:
          type: integer
          format: int32
          default: 25
          minimum: 1
          maximum: 250
      responses:
        '200':
          description: 'Returned with the page of unassigned combinations (possibly an empty `results` array if

            no combinations exist or if combinations have not yet been generated for this tenant).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSpacePermissionCombinationsResponse'
        '400':
          description: 'Returned if the `cursor` query parameter is malformed, or if `limit` is not an integer

            in the range `1`–`250`.'
          content: {}
        '401':
          description: Returned if the authentication credentials are incorrect or missing from the request.
          content: {}
        '404':
          description: Returned if the calling user does not have permission or the resource is not found.
          content: {}
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - read:configuration:confluence
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - read:configuration:confluence
      x-atlassian-connect-scope: ADMIN
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-experimental: true
    post:
      tags:
      - Space Permission Transition
      operationId: generateSpacePermissionCombinations
      summary: Generate space permission combinations
      description: 'Submits a task to refresh the space permission combinations in the database, which identifies

        all unique permission combinations across the site. This provides permission combination IDs

        that can be used with the assign-roles and remove-access endpoints.


        **Permissions required**:

        User must be a Confluence administrator.'
      responses:
        '202':
          description: Returned if the generation task is successfully submitted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkTransitionTaskResponse'
        '401':
          description: Returned if the authentication credentials are incorrect or missing from the request.
          content: {}
        '404':
          description: Returned if the calling user does not have permission or the resource is not found.
          content: {}
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - write:configuration:confluence
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - write:configuration:confluence
      x-atlassian-connect-scope: ADMIN
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-experimental: true
  /space-permissions/transition/role-assignments:
    post:
      tags:
      - Space Permission Transition
      operationId: bulkAssignSpacePermissionRoles
      summary: Bulk assign space permission roles
      description: 'Bulk assigns roles for one or more permission combination IDs obtained from the space permission

        combinations. Supports targeting all spaces, specific spaces, or excluding specific spaces.


        **Permissions required**:

        User must be a Confluence administrator.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkAssignRolesRequest'
        required: true
      responses:
        '202':
          description: Returned if the bulk assign roles task is successfully submitted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkTransitionTaskResponse'
        '400':
          description: Returned if the request is invalid (e.g., empty assignments, missing space selection).
          content: {}
        '401':
          description: Returned if the authentication credentials are incorrect or missing from the request.
          content: {}
        '404':
          description: Returned if the calling user does not have permission or the resource is not found.
          content: {}
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - write:configuration:confluence
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - write:configuration:confluence
      x-atlassian-connect-scope: ADMIN
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-experimental: true
  /space-permissions/transition/access-removals:
    post:
      tags:
      - Space Permission Transition
      operationId: bulkRemoveSpacePermissionAccess
      summary: Bulk remove space permission access
      description: 'Bulk removes access for one or more permission combination IDs obtained from the space permission

        combinations. This removes all space permissions for the specified combinations across

        the targeted spaces.


        **Permissions required**:

        User must be a Confluence administrator.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkRemoveAccessRequest'
        required: true
      responses:
        '202':
          description: Returned if the bulk remove access task is successfully submitted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkTransitionTaskResponse'
        '400':
          description: Returned if the request is invalid (e.g., empty permission combination IDs, missing space selection).
          content: {}
        '401':
          description: Returned if the authentication credentials are incorrect or missing from the request.
          content: {}
        '404':
          description: Returned if the calling user does not have permission or the resource is not found.
          content: {}
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - write:configuration:confluence
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - write:configuration:confluence
      x-atlassian-connect-scope: ADMIN
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-experimental: true
  /space-permissions/transition/tasks/{taskId}:
    get:
      tags:
      - Space Permission Transition
      operationId: getSpacePermissionTransitionTaskStatus
      summary: Get space permission transition task status
      description: 'Retrieves the status of an async space permission transition task. Use the taskId returned

        from the generate-combinations, assign-roles, or remove-access endpoints to poll for

        progress and completion.


        **Permissions required**:

        User must be a Confluence administrator.'
      parameters:
      - name: taskId
        in: path
        required: true
        description: The ID of the async task, as returned by the generate-combinations, assign-roles, or remove-access endpoints.
        schema:
          type: string
      responses:
        '200':
          description: Returned if the task is found and the status is successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkTransitionTaskStatusResponse'
        '401':
          description: Returned if the authentication credentials are incorrect or missing from the request.
          content: {}
        '404':
          description: Returned if the task does not exist or the calling user does not have permission to view it.
          content: {}
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - read:configuration:confluence
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - read:configuration:confluence
      x-atlassian-connect-scope: ADMIN
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-experimental: true
components:
  schemas:
    BulkTransitionTaskResponse:
      type: object
      required:
      - taskId
      - status
      - statusUrl
      properties:
        taskId:
          type: string
          description: The ID of the async task.
        status:
          type: string
          description: The current status of the task.
          enum:
          - IN_PROGRESS
          - COMPLETED
          - FAILED
        statusUrl:
          type: string
          description: URL to poll for task progress.
    BulkTransitionPrincipalTypeAssignment:
      type: object
      required:
      - principalType
      - removeAccess
      properties:
        principalType:
          type: string
          description: The type of principal.
          enum:
          - USER
          - GROUP
          - GUEST
          - ANONYMOUS
          - ALL_LICENSED_USERS_USER_CLASS
          - ALL_PRODUCT_ADMINS_USER_CLASS
          - APP
        removeAccess:
          type: boolean
          description: Whether to remove access for this principal type instead of assigning a role.
        roleId:
          type:
          - string
          - 'null'
          description: The UUID of the space role to assign. Required when removeAccess is false.
    BulkTransitionRoleAssignment:
      type: object
      required:
      - permissionCombinationId
      - principalTypeAssignments
      properties:
        permissionCombinationId:
          type: string
          description: The ID of the permission combination.
        principalTypeAssignments:
          type: array
          description: List of principal type assignments.
          items:
            $ref: '#/components/schemas/BulkTransitionPrincipalTypeAssignment'
    BulkAssignRolesRequest:
      type: object
      required:
      - assignments
      - spaceSelection
      properties:
        assignments:
          type: array
          description: List of role assignments to apply.
          items:
            $ref: '#/components/schemas/BulkTransitionRoleAssignment'
        spaceSelection:
          $ref: '#/components/schemas/BulkTransitionSpaceSelection'
    BulkRemoveAccessRequest:
      type: object
      required:
      - permissionCombinationIds
      - spaceSelection
      properties:
        permissionCombinationIds:
          type: array
          description: List of permission combination IDs to remove access for.
          items:
            type: string
        spaceSelection:
          $ref: '#/components/schemas/BulkTransitionSpaceSelection'
    BulkTransitionSpaceSelection:
      type: object
      required:
      - spaceType
      properties:
        spaceType:
          type: string
          description: The space selection type.
          enum:
          - ALL
          - ALL_EXCEPT_PERSONAL
          - ALL_EXCEPT_SPECIFIC
          - PERSONAL
          - SPECIFIC
        selectedSpaces:
          type: array
          description: List of specific spaces. Required when spaceType is SPECIFIC or ALL_EXCEPT_SPECIFIC.
          items:
            $ref: '#/components/schemas/BulkTransitionSpaceTarget'
    BulkTransitionSpaceTarget:
      type: object
      required:
      - id
      - key
      properties:
        id:
          type: string
          description: The space ID.
        key:
          type: string
          description: The space key.
    BulkTransitionDecodedPermission:
      type: object
      required:
      - id
      - displayName
      properties:
        id:
          type: string
          description: The platform id of the permission (e.g. `VIEW_CONTENT`).
        displayName:
          type: string
          description: Human-readable name of the permission.
    BulkTransitionTaskStatusResponse:
      type: object
      required:
      - taskId
      - status
      properties:
        taskId:
          type: string
          description: The ID of the task.
        status:
          type: string
          description: The current status of the task.
          enum:
          - IN_PROGRESS
          - COMPLETED
          - FAILED
        errorMessage:
          type:
          - string
          - 'null'
          description: Human-readable error message describing why the task failed. Only present when status is FAILED.
    ListSpacePermissionCombinationsResponse:
      type: object
      required:
      - results
      properties:
        results:
          type: array
          description: One page of unassigned permission combinations, sorted by principalCount descending.
          items:
            $ref: '#/components/schemas/BulkTransitionCombinationEntry'
        generatedAt:
          type:
          - string
          - 'null'
          description: 'ISO-8601 timestamp of the last audit run that populated the combinations table.

            Absent if the audit task has never run on this tenant.'
        cursor:
          type:
          - string
          - 'null'
          description: Opaque cursor for the next page. Absent when no further results exist.
    BulkTransitionCombinationEntry:
      type: object
      required:
      - combinationId
      - spaceCount
      - principalCount
      - permissions
      - principalTypes
      properties:
        combinationId:
          type: string
          description: The opaque id identifying this unique combination of space permissions. Pass directly to the bulk role-assignments or access-removals endpoints.
        spaceCount:
          type: integer
          format: int64
          description: Number of spaces that currently have this combination.
        principalCount:
          type: integer
          format: int64
          description: Number of principals (users / groups / etc.) that currently have this combination.
        permissions:
          type: array
          description: The decoded space permissions that make up this combination.
          items:
            $ref: '#/components/schemas/BulkTransitionDecodedPermission'
        principalTypes:
          type: array
          description: 'The principal types that currently hold this combination and can be reassigned via the

            bulk role-assignments endpoint. Use this to know which `principalType` entries are valid

            to include in the bulk-assign request for this combination.'
          items:
            type: string
            enum:
            - USER
            - GROUP
            - GUEST
            - ANONYMOUS
            - ALL_LICENSED_USERS_USER_CLASS
            - ALL_PRODUCT_ADMINS_USER_CLASS
            - APP
            - TEAM
  securitySchemes:
    basicAuth:
      type: http
      description: You can access this resource via basic auth.
      scheme: basic
    oAuthDefinitions:
      type: oauth2
      description: This API uses OAuth 2 with the authorizationCode grant flow.
      flows:
        authorizationCode:
          authorizationUrl: https://auth.atlassian.com/authorize
          tokenUrl: https://auth.atlassian.com/oauth/token
          scopes:
            read:page:confluence: View pages and blogposts and their properties.
            read:space:confluence: View spaces and their properties.
            read:attachment:confluence: View attachments and their properties.
            read:comment:confluence: View comments and their properties.
            read:custom-content:confluence: View custom content and their properties.
            read:task:confluence: View tasks.
            read:whiteboard:confluence: View whiteboards and their properties.
            read:database:confluence: View databases and their properties.
            read:embed:confluence: View Smart Links in the content tree and their properties.
            read:folder:confluence: View folders and their properties.
            read:hierarchical-content:confluence: View children and descendants in the content tree.
            write:space:confluence: Create and update spaces and their properties.
            write:page:confluence: Create and update pages and blog posts and their properties.
            write:comment:confluence: Create and update comments and their properties.
            write:custom-content:confluence: Create and update custom content and their properties.
            write:whiteboard:confluence: Create and update whiteboards and their properties.
            write:database:confluence: Create and update databases and their properties.
            write:embed:confluence: Create and update Smart Links in the content tree and their properties.
            write:folder:confluence: Create and update folders and their properties.
            write:app-data:confluence: Create, update and delete app properties.
            delete:custom-content:confluence: Delete custom content.
            delete:page:confluence: Delete pages and blog posts.
            delete:comment:confluence: Delete comments.
            delete:whiteboard:confluence: Delete whiteboards.
            delete:database:confluence: Delete databases.
            delete:embed:confluence: Delete Smart Links in the content tree.
            delete:folder:confluence: Delete folders.
externalDocs:
  description: The online and complete version of the Confluence Cloud REST API docs.
  url: https://developer.atlassian.com/cloud/confluence/rest/v2
x-atlassian-narrative:
  documents:
  - title: About
    anchor: about
    body: This is the reference for the Confluence Cloud REST API v2, with definitions and performance intended to be an improvement over v1. You can click on the meatball menu in the upper right to download the spec or Postman collection.
  - title: Authentication and authorization
    anchor: auth
    body: '**Authentication:** If you are building a Cloud app, authentication is implemented via JWT or Oauth 2.0, depending on what you''re building (see [Authentication for apps](https://developer.atlassian.com/cloud/confluence/authentication-for-apps/)). Otherwise, if you are authenticating directly against the REST API, the REST API supports basic auth (see [Basic auth for REST APIs](https://developer.atlassian.com/cloud/confluence/basic-auth-for-rest-apis/)).


      **Authorization:** If you are building a Cloud app, authorization can be implemented by [scopes](https://developer.atlassian.com/cloud/confluence/scopes/) or by [OAuth 2.0 user impersonation](https://developer.atlassian.com/cloud/confluence/oauth-2-jwt-bearer-tokens-for-apps). Otherwise, if you are making calls directly against the REST API, authorization is based on the user used in the authentication process.


      See [Security overview](https://developer.atlassian.com/cloud/confluence/security-overview/) for more details on authentication and authorization.'
  - title: Using the REST API
    anchor: using
    body: "**Pagination:** The Confluence REST API v2 uses cursor-based pagination: a method that returns a response with multiple objects can only return a limited number at one time. This limits the size of responses and conserves server resources.\n\nUse the 'limit' and 'cursor' parameters on endpoints that return multiple objects to work with pagination. First, make a request with your desired limit in the 'limit' parameter, then observe the `Link` header in the response. If there are additional entities to be retrieved, the `next` URL in the `Link` header will allow you to retrieve the next set of results. This relative URL will also be available under the `_links.next` property of paginated responses. \n\nFor example, the following request will return 5 page objects (if there are 5 present in the target site).\n```\nGET /wiki/api/v2/pages?limit=5\n```\n\nIf there are additional pages available, the `Link` header will look like:\n```\n</wiki/api/v2/pages?limit=5&cursor=<cursor token>>; rel=\"next\"\n```\nThe URL within the `Link` header will allow you to access the next 5 pages, while the `rel=\"next\"` denotes that the URL refers to the \"next\" set of pages. Relations for a single URL are separated by semicolons (;) and URLs are separated by commas (,)\nIf there are no related URLs, the `Link` header will not be present in the response and neither will the `next` property for `_links` in the response body."