Atlassian Space Permissions API

openapi: 3.2.0
info:
  title: Atlassian The Confluence Cloud REST Space Permissions API
  description: This document describes the REST API and resources provided by Confluence. The REST APIs are for developers who want to integrate Confluence into their application and for administrators who want to script interactions with the Confluence server.Confluence's REST APIs provide access to resources (data entities) via URI paths. To use a REST API, your application will make an HTTP request and parse the response. The response format is JSON. Your methods will be the standard HTTP methods like GET, PUT, POST and DELETE. Because the REST API is based on open standards, you can use any web development language to access the API.
  termsOfService: https://atlassian.com/terms/
  version: 1.0.0
servers:
- url: //your-domain.atlassian.net
tags:
- name: Space Permissions
  description: ''
paths:
  /wiki/rest/api/space/{spaceKey}/permission:
    post:
      tags:
      - Space Permissions
      summary: Atlassian Add New Permission To Space
      description: 'Adds new permission to space.<br><br>If the permission to be added is a group permission, the group can be identified<br>by its group name or group id.<br><br>Note: Apps cannot access this REST resource - including when utilizing user impersonation.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw) required**:<br>''Admin'' permission for the space.'
      operationId: atlassianAddpermissiontospace
      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
  /wiki/rest/api/space/{spaceKey}/permission/custom-content:
    post:
      tags:
      - Space Permissions
      summary: Atlassian Add New Custom Content Permission To Space
      description: 'Adds new custom content permission to space.<br><br>If the permission to be added is a group permission, the group can be identified<br>by its group name or group id.<br><br>Note: Only apps can access this REST resource and only make changes to the respective app permissions.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw) required**:<br>''Admin'' permission for the space.'
      operationId: atlassianAddcustomcontentpermissions
      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
  /wiki/rest/api/space/{spaceKey}/permission/{id}:
    delete:
      tags:
      - Space Permissions
      summary: Atlassian Remove A Space Permission
      description: 'Removes a space permission. Note that removing Read Space permission for a user or group will remove all<br>the space permissions for that user or group.<br><br>Note: Apps cannot access this REST resource - including when utilizing user impersonation.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw) required**:<br>''Admin'' permission for the space.'
      operationId: atlassianRemovepermission
      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
components:
  schemas:
    GenericLinks:
      type: object
      additionalProperties:
        oneOf:
        - type: object
          additionalProperties: true
        - type: string
    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.'
    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```"
    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```"
    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\n\nfor `type=group`, identifier should be the groupId. We are deprecating groupName support in mid-2024 \nfor this field but still accept it in the interim."
      description: The user or group that the permission applies to.
  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.
externalDocs:
  description: The online and complete version of the Confluence Cloud REST API docs.
  url: https://developer.atlassian.com/cloud/confluence/rest/
x-atlassian-narrative:
  documents:
  - title: About
    anchor: about
    body: 'This is the reference for the Confluence Cloud REST API. This API is the primary way to get and

      modify data in Confluence Cloud, whether you are developing an app or any other integration.

      Use it to interact with Confluence entities, like pages and blog posts, spaces, users, groups,

      and more.'
  - 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 are building (see [Security overview](https://developer.atlassian.com/cloud/confluence/security-overview/)). 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: Status codes
    anchor: status-code
    body: "The Confluence REST API uses the [standard HTTP status codes](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html).\n\nResponses that return an error status code will also return a response body, similar to the following:\n```json\n{\n  \"statusCode\": 404,\n  \"data\": {\n    \"authorized\": false,\n    \"valid\": false,\n    \"errors\": [\n      {\n        \"message\": {\n          \"translation\": \"This is an example error message.\",\n          \"args\": []\n        }\n      }\n    ],\n    \"successful\": false\n  },\n  \"message\": \"This is an example error message.\"\n}\n```"
  - title: Using the REST API
    anchor: using
    body: '**Expansion:** The Confluence REST API uses resource expansion: some parts of a resource are not returned unless explicitly specified. This simplifies responses and minimizes network traffic.


      To expand part of a resource in a request, use the `expand` query parameter and specify the entities to be expanded. If you need to expand nested entities, use the `.` dot notation. For example, the following request will expand information about the requested content''s space and labels:

      ```

      GET /wiki/rest/api/content/{id}?expand=space,metadata.labels

      ```

      **Pagination:** The Confluence REST API uses 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.


      Use the ''limit'' and ''start'' query parameters to specify pagination:


      - `limit` is the number of objects to return per page. This may be restricted by system limits.

      - `start` is the index of the first item returned in the page of results. The base index is 0.


      For example, the following request will return ten content objects, starting from the fifth object.

      ```

      GET /wiki/rest/api/content?start=4&limit=10

      ```

      **Special headers:**


      - `X-Atlassian-Token: no-check` request header must be specified for methods

      that are protected from Cross Site Request Forgery (XSRF/CSRF) attacks. This is

      stated in the method description, if required. For more information, see this

      [KB article](https://confluence.atlassian.com/cloudkb/xsrf-check-failed-when-calling-cloud-apis-826874382.html).'
  - title: Capabilities
    anchor: capabilities
    body: '**Webhooks:** A webhook is a user-defined callback over HTTP. You can use Confluence webhooks to notify your app or web application when certain events occur in Confluence. For example, when a page is created or updated. To learn more, see [Webhooks](https://developer.atlassian.com/cloud/confluence/modules/webhook/).


      **Content properties:** Content properties are a key-value storage associated with a piece of Confluence content. If you are building an app, this is one form of persistence that you can use. You can use the Confluence REST API to get, update, and delete content properties. To learn more, see [Content properties in the REST API](https://developer.atlassian.com/cloud/confluence/content-properties/).


      **CQL:** The Confluence Query Language (CQL) allows you to perform complex searches for content using an SQL-like syntax in the `search` resource. To learn more, see [Advanced searching using CQL](https://developer.atlassian.com/cloud/confluence/advanced-searching-using-cql/).'