Confluence Space permissions API

openapi: 3.2.0
info:
  title: Confluence Space permissions API
  version: '1.0'
  description: 'Operations tagged Space permissions across 2 of this provider''s published API definitions: confluence-rest-v1-openapi.json, confluence-rest-v2-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: //your-domain.atlassian.net
- 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 Permissions
  description: ''
paths:
  /wiki/rest/api/space/{spaceKey}/permission:
    post:
      tags:
      - Space Permissions
      summary: Add new permission to space
      description: 'Adds new permission to space.


        If the permission to be added is a group permission, the group can be identified

        by its group name or group id.


        Note: Apps cannot access this REST resource - including when utilizing user impersonation.


        **Permissions required**:

        ''Admin'' permission for the space.'
      operationId: addPermissionToSpace
      parameters:
      - name: spaceKey
        in: path
        description: The key of the space to be queried for its content.
        required: true
        schema:
          type: string
      requestBody:
        description: The permission to be created.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpacePermissionRequest'
        required: true
      responses:
        '200':
          description: Returned if the requested content is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpacePermissionV2'
        '400':
          description: 'Used for various errors. Such as:

            - Permission already exists for the given user or group.

            - ''read space'' permission doesn''t exist for the given user or group.

            - No group found with the given groupName or groupId'
          content: {}
        '401':
          description: 'Returned if the authentication credentials are incorrect or missing

            from the request.'
          content: {}
        '403':
          description: Returned if the user isn't authorized.
          content: {}
        '404':
          description: 'Returned if any of the following is true:

            - There is no space with the given key.

            - The calling user does not have permission to view the space.'
          content: {}
      x-codegen-request-body-name: body
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - read:space.permission:confluence
        - write:space.permission:confluence
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - read:space.permission:confluence
        - write:space.permission:confluence
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-atlassian-connect-scope: INACCESSIBLE
    servers:
    - url: //your-domain.atlassian.net
  /wiki/rest/api/space/{spaceKey}/permission/custom-content:
    post:
      tags:
      - Space Permissions
      summary: Add new custom content permission to space
      description: 'Adds new custom content permission to space.


        If the permission to be added is a group permission, the group can be identified

        by its group name or group id.


        Note: Only apps can access this REST resource and only make changes to the respective app permissions.


        **Permissions required**:

        ''Admin'' permission for the space.'
      operationId: addCustomContentPermissions
      parameters:
      - name: spaceKey
        in: path
        description: The key of the space to be queried for its content.
        required: true
        schema:
          type: string
      requestBody:
        description: The permissions to be created.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpacePermissionCustomContent'
        required: true
      responses:
        '200':
          description: Returned if the requested content is returned.
          content: {}
        '400':
          description: 'Used for various errors. Such as:

            - Permission already exists for the given user or group.

            - ''read space'' permission doesn''t exist for the given user or group.

            - No group found with the given groupName or groupId'
          content: {}
        '401':
          description: 'Returned if the authentication credentials are incorrect or missing

            from the request.'
          content: {}
        '403':
          description: Returned if the user isn't authorized.
          content: {}
        '404':
          description: 'Returned if any of the following is true:

            - There is no space with the given key.

            - The calling user does not have permission to view the space.'
          content: {}
      x-codegen-request-body-name: body
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - read:space.permission:confluence
        - write:space.permission:confluence
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - read:space.permission:confluence
        - write:space.permission:confluence
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-atlassian-connect-scope: WRITE
    servers:
    - url: //your-domain.atlassian.net
  /wiki/rest/api/space/{spaceKey}/permission/{id}:
    delete:
      tags:
      - Space Permissions
      summary: Remove a space permission
      description: 'Removes a space permission. Note that removing Read Space permission for a user or group will remove all

        the space permissions for that user or group.


        Note: Apps cannot access this REST resource - including when utilizing user impersonation.


        **Permissions required**:

        ''Admin'' permission for the space.'
      operationId: removePermission
      parameters:
      - name: spaceKey
        in: path
        description: The key of the space to be queried for its content.
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Id of the permission to be deleted.
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: Permission successfully removed.
          content: {}
        '400':
          description: 'Used for various errors. Such as:

            - All of the admin permissions cannot be removed from a space.'
          content: {}
        '401':
          description: 'Returned if the authentication credentials are incorrect or missing

            from the request.'
          content: {}
        '403':
          description: Returned if the user isn't authorized.
          content: {}
        '404':
          description: 'Returned if any of the following is true:

            - There is no permission with the given id.

            - There is no space with the given key.

            - The calling user does not have permission to view the space.'
          content: {}
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - write:space.permission:confluence
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - write:space.permission:confluence
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-atlassian-connect-scope: INACCESSIBLE
    servers:
    - url: //your-domain.atlassian.net
  /spaces/{id}/permissions:
    get:
      tags:
      - Space Permissions
      operationId: getSpacePermissionsAssignments
      summary: Get space permissions assignments
      description: 'Returns space permission assignments for a specific space.


        **Permissions required**:

        Permission to view the space.'
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the space to be returned.
        schema:
          format: int64
          type: integer
      - name: cursor
        in: query
        required: false
        description: Used for pagination, this opaque cursor will be returned in the `next` URL in the `Link` response header. Use the relative URL in the `Link` header to retrieve the `next` set of results.
        schema:
          type: string
      - name: limit
        in: query
        description: Maximum number of assignments to return. If more results exist, use the `Link` response header to retrieve a relative URL that will return the next set of results.
        schema:
          format: int32
          default: 25
          minimum: 1
          maximum: 250
          type: integer
      responses:
        '200':
          description: Returned if the requested assignments are returned.
          content:
            application/json:
              schema:
                title: MultiEntityResult<SpacePermissionAssignment>
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/SpacePermissionAssignment'
                  _links:
                    $ref: '#/components/schemas/MultiEntityLinks'
        '400':
          description: Returned if an invalid request is provided.
          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 to view the

            requested space permission assignments or the space was not found.'
          content: {}
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - read:space:confluence
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - read:space:confluence
      x-atlassian-connect-scope: READ
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
    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.
  /space-permissions:
    get:
      tags:
      - Space Permissions
      operationId: getAvailableSpacePermissions
      summary: Get available space permissions
      description: 'Retrieves the available space permissions.


        Available on tenants with Role-Based Access Control.


        **Permissions required**:

        Permission to access the Confluence site.'
      parameters:
      - name: cursor
        in: query
        required: false
        description: Used for pagination, this opaque cursor will be returned in the `next` URL in the `Link` response header. Use the relative URL in the `Link` header to retrieve the `next` set of results.
        schema:
          type: string
      - name: limit
        in: query
        description: Maximum number of space permissions to return. If more results exist, use the `Link` response header to retrieve a relative URL that will return the next set of results.
        schema:
          format: int32
          default: 25
          minimum: 1
          maximum: 250
          type: integer
      responses:
        '200':
          description: Returned if the requested space permissions are retrieved.
          content:
            application/json:
              schema:
                title: MultiEntityResult<SpacePermission>
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/SpacePermission'
                  _links:
                    $ref: '#/components/schemas/MultiEntityLinks'
        '400':
          description: Returned if an invalid request is provided.
          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 to view the

            available space permissions.'
          content: {}
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - read:space.permission:confluence
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - read:space.permission:confluence
      x-atlassian-connect-scope: READ
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
    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.
components:
  schemas:
    SpacePermissionRequest:
      required:
      - subject
      - operation
      type: object
      additionalProperties: true
      properties:
        subject:
          $ref: '#/components/schemas/PermissionSubject'
        operation:
          required:
          - key
          - target
          type: object
          properties:
            key:
              type: string
              enum:
              - administer
              - archive
              - copy
              - create
              - delete
              - export
              - move
              - purge
              - purge_version
              - read
              - restore
              - restrict_content
              - update
              - use
            target:
              type: string
              description: The space or content type that the operation applies to.
              enum:
              - page
              - blogpost
              - comment
              - attachment
              - space
        _links:
          $ref: '#/components/schemas/GenericLinks'
      description: "This object represents the request for the single space permission. Permissions consist of\none operation object with an accompanying subjects object.\n\nThe following combinations of `operation.key` and `operation.target` values are\nvalid for the `operation` object:\n``` bash\n'create': 'page', 'blogpost', 'comment', 'attachment'\n'read': 'space'\n'delete': 'page', 'blogpost', 'comment', 'attachment', 'space'\n'export': 'space'\n'administer': 'space'\n'archive': 'page'\n'restrict_content': 'space'\n```\n\nFor example, to enable Delete Own permission, set the `operation` object to the following:\n```\n\"operation\": {\n    \"key\": \"delete\",\n    \"target\": \"space\"\n}\n```\nTo enable Add/Delete Restrictions permissions, set the `operation` object to the following:\n```\n\"operation\": {\n    \"key\": \"restrict_content\",\n    \"target\": \"space\"\n}\n```"
    SpacePermissionCustomContent:
      required:
      - operations
      - subject
      type: object
      properties:
        subject:
          $ref: '#/components/schemas/PermissionSubject'
        operations:
          type: array
          items:
            required:
            - access
            - key
            - target
            type: object
            properties:
              key:
                type: string
                description: The operation type
                enum:
                - read
                - create
                - delete
              target:
                type: string
                description: The custom content type
              access:
                type: boolean
                description: Grant or restrict access
      description: 'This object represents a list of space permissions for custom content type for an individual user. Permissions consist of

        a subjects object and a list with at least one operation object.'
    SpacePermissionV2:
      required:
      - id
      - subject
      - operation
      type: object
      properties:
        id:
          type: integer
          format: int64
        subject:
          $ref: '#/components/schemas/PermissionSubject'
        operation:
          required:
          - key
          - target
          type: object
          properties:
            key:
              type: string
              enum:
              - administer
              - archive
              - copy
              - create
              - delete
              - export
              - move
              - purge
              - purge_version
              - read
              - restore
              - restrict_content
              - update
              - use
            target:
              type: string
              description: The space or content type that the operation applies to.
              enum:
              - page
              - blogpost
              - comment
              - attachment
              - space
        _links:
          $ref: '#/components/schemas/GenericLinks'
      description: "This object represents a single space permission. Permissions consist of\nat least one operation object with an accompanying subjects object.\n\nThe following combinations of `operation.key` and `operation.target` values are\nvalid for the `operation` object:\n``` bash\n'create': 'page', 'blogpost', 'comment', 'attachment'\n'read': 'space'\n'delete': 'page', 'blogpost', 'comment', 'attachment', 'space'\n'export': 'space'\n'administer': 'space'\n'archive': 'page'\n'restrict_content': 'space'\n```\n\nFor example, to enable Delete Own permission, set the `operation` object to the following:\n```\n\"operation\": {\n    \"key\": \"delete\",\n    \"target\": \"space\"\n}\n```\nTo enable Add/Delete Restrictions permissions, set the `operation` object to the following:\n```\n\"operation\": {\n    \"key\": \"restrict_content\",\n    \"target\": \"space\"\n}\n```"
    GenericLinks:
      type: object
      additionalProperties:
        oneOf:
        - type: object
          additionalProperties: true
        - type: string
    PermissionSubject:
      required:
      - identifier
      - type
      type: object
      properties:
        type:
          type: string
          enum:
          - user
          - group
        identifier:
          type: string
          description: 'for `type=user`, identifier should be user''s accountId or `anonymous` for anonymous users


            for `type=group`, identifier should be the groupId.'
      description: The user or group that the permission applies to.
    SpacePermission:
      type: object
      properties:
        id:
          type: string
          description: The identifier for the space permission.
        displayName:
          type: string
          description: The display name for the space permission.
        description:
          type: string
          description: Describes the space permission’s usage.
        requiredPermissionIds:
          type: array
          items:
            type: string
          description: The permissions required for this permission to be enabled.
    MultiEntityLinks:
      type: object
      properties:
        next:
          type: string
          description: 'Used for pagination. Contains the relative URL for the next set of results, using a cursor query parameter.

            This property will not be present if there is no additional data available.'
        base:
          type: string
          description: Base url of the Confluence site.
    SpacePermissionAssignment:
      type: object
      properties:
        id:
          type: string
          description: ID of the space permission.
        principal:
          type: object
          description: The entity the space permissions corresponds to.
          properties:
            type:
              enum:
              - user
              - group
              - role
              type: string
            id:
              type: string
              description: ID of the entity.
        operation:
          type: object
          description: The operation the space permission corresponds to.
          properties:
            key:
              enum:
              - use
              - create
              - read
              - update
              - delete
              - copy
              - move
              - export
              - purge
              - purge_version
              - administer
              - restore
              - create_space
              - restrict_content
              - archive
              type: string
              description: The type of operation.
            targetType:
              enum:
              - page
              - blogpost
              - comment
              - attachment
              - whiteboard
              - database
              - embed
              - folder
              - space
              - application
              - userProfile
              type: string
              description: The type of entity the operation type targets.
  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:confluence-content.all: Read all content, including content body (expansions permitted). Note, APIs using this scope may also return data allowed by read:confluence-space.summary. However, this scope is not a substitute for read:confluence-space.summary.
            read:confluence-content.permission: Read content permissions.
            read:confluence-content.summary: Read a summary of the content, which is the content without expansions. Note, APIs using this scope may also return data allowed by read:confluence-space.summary. However, this scope is not a substitute for read:confluence-space.summary.
            write:confluence-content: Permits the creation of pages, blogs, comments and questions.
            read:confluence-space.summary: Read a summary of space information without expansions.
            write:confluence-space: Create, update and delete space information.
            write:confluence-file: Upload attachments.
            read:confluence-props: Read content properties.
            write:confluence-props: Write content properties.
            search:confluence: Search Confluence. Note, APIs using this scope may also return data allowed by read:confluence-space.summary and read:confluence-content.summary. However, this scope is not a substitute for read:confluence-space.summary or read:confluence-content.summary.
            manage:confluence-configuration: Manage global settings.
            read:confluence-groups: Read user groups.
            write:confluence-groups: Create, remove and update user groups.
            read:confluence-user: Read users.
            readonly:content.attachment:confluence: Download attachments of a Confluence page or blogpost that you have access to.
            read:content:confluence: View content.
            read:content-details:confluence: View content details.
            write:content:confluence: Create and update content.
            delete:content:confluence: Delete content.
            read:space-details:confluence: View space details.
            read:analytics.content:confluence: View analytics for content.
            read:audit-log:confluence: View audit records.
            write:audit-log:confluence: Create audit records.
            read:configuration:confluence: View Confluence settings.
            write:configuration:confluence: Update Confluence settings.
            read:page:confluence: View pages.
            write:page:confluence: Create and update pages.
            delete:page:confluence: Delete pages.
            read:blogpost:confluence: View blogposts.
            write:blogpost:confluence: Create and update blogposts.
            delete:blogpost:confluence: Delete blogposts.
            read:whiteboard:confluence: View whiteboards.
            write:whiteboard:confluence: Create and update whiteboards.
            delete:whiteboard:confluence: Delete whiteboards.
            read:custom-content:confluence: View custom content.
            write:custom-content:confluence: Create and update custom content.
            delete:custom-content:confluence: Delete custom content.
            read:attachment:confluence: View and download content attachments.
            write:attachment:confluence: Create and update attachments.
            delete:attachment:confluence: Delete attachments.
            read:comment:confluence: View comments.
            write:comment:confluence: Create and update comments.
            delete:comment:confluence: Delete comments.
            read:template:confluence: View content templates.
            write:template:confluence: Create, update and delete content templates.
            read:label:confluence: View labels.
            write:label:confluence: Add and remove labels.
            read:content.permission:confluence: Check content permissions.
            read:content.property:confluence: View content properties.
            write:content.property:confluence: Create, update and delete content properties.
            read:content.restriction:confluence: View content restrictions.
            write:content.restriction:confluence: Update content restrictions.
            read:content.metadata:confluence: View content summaries.
            read:watcher:confluence: View content watchers.
            write:watcher:confluence: Add and remove content watchers.
            read:group:confluence: View groups.
            write:group:confluence: Create and delete groups.
            read:inlinetask:confluence: View tasks.
            write:inlinetask:confluence: Update tasks.
            read:relation:confluence: View entity relationships.
            write:relation:confluence: Create and update entity relationships.
            read:space:confluence: View spaces.
            write:space:confluence: Create and update spaces.
            delete:space:confluence: Delete spaces.
            read:space.permission:confluence: View space permissions.
            write:space.permission:confluence: Update space permissions.
            read:space.property:confluence: View space properties.
            write:space.property:confluence: Create, update and delete space properties.
            read:user.property:confluence: View user properties.
            write:user.property:confluence: Create, update and delete user properties.
            read:space.setting:confluence: View space settings.
            write:space.setting:confluence: Update space settings.
            read:user:confluence: View user details.
            moderate:core-content:confluence: Moderate core contents
            moderate:comment:confluence: Moderate comments
            read:email-address:confluence: View email addresses of all users regardless of the user’s profile visibility settings.
x-refined-from:
- confluence-rest-v1-openapi.json
- confluence-rest-v2-openapi.json