Confluence Admin Key API

openapi: 3.2.0
info:
  title: Confluence Cloud REST API v2 Admin Key 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: Admin Key
  description: 'The Admin Key feature is only offered with Confluence Cloud Premium and Enterprise to organization or site admins.


    **NOTE:** Users can only make calls to our public REST APIs using a valid Admin Key by adding the following HTTP header on their requests: `Atl-Confluence-With-Admin-Key: true`. Visit the Confluence Cloud Changelog for more details.'
paths:
  /admin-key:
    get:
      tags:
      - Admin Key
      operationId: getAdminKey
      summary: Get Admin Key
      description: 'Returns information about the admin key if one is currently enabled for the calling user within the site.


        **Permissions required**:

        User must be an organization or site admin.'
      responses:
        '200':
          description: Returned if an admin key is currently enabled for the calling user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminKeyResponse'
        '401':
          description: Returned if the authentication credentials are incorrect or missing from the request.
          content: {}
        '404':
          description: Returned if the calling user does not currently have an admin key, if the calling user does not have permission to use admin keys, or if the site is not a Confluence Cloud Premium or Enterprise instance.
          content: {}
      x-atlassian-connect-scope: INACCESSIBLE
    post:
      tags:
      - Admin Key
      operationId: enableAdminKey
      summary: Enable Admin Key
      description: 'Enables admin key access for the calling user within the site. If an admin key already exists for the user, a new one will be issued with an updated expiration time.


        **Note:** The `durationInMinutes` field within the request body is optional. If the request body is empty or if the `durationInMinutes` is set to 0 minutes, a new admin key will be issued to the calling user with a default duration of 10 minutes.


        **Permissions required**:

        User must be an organization or site admin.'
      requestBody:
        $ref: '#/components/requestBodies/AdminKeyRequest'
      responses:
        '200':
          description: Returned if a new admin key is successfully issued for the calling user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminKeyResponse'
        '400':
          description: Returned if the request body contains an invalid `durationInMinutes`.
          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 use admin keys or if the site is not a Confluence Cloud Premium or Enterprise instance.
          content: {}
      x-atlassian-connect-scope: INACCESSIBLE
    delete:
      tags:
      - Admin Key
      operationId: disableAdminKey
      summary: Disable Admin Key
      description: 'Disables admin key access for the calling user within the site.


        **Permissions required**:

        User must be an organization or site admin.'
      responses:
        '204':
          description: Returned if admin key access was successfully disabled for the calling user or if the user did not have an admin key in the first place.
          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 use admin keys or if the site is not a Confluence Cloud Premium or Enterprise instance.
          content: {}
      x-atlassian-connect-scope: INACCESSIBLE
components:
  requestBodies:
    AdminKeyRequest:
      required: false
      content:
        application/json:
          schema:
            type: object
            properties:
              durationInMinutes:
                type: integer
                format: int32
                description: The requested duration of admin key access in minutes, up to a maximum of 60 minutes, after which the issued admin key will automatically expire.
                example: 60
  schemas:
    AdminKeyResponse:
      type: object
      properties:
        accountId:
          type: string
          description: User identifier.
        expirationTime:
          type: string
          format: date-time
          description: Timestamp in UTC that represents when the admin key will expire. In format "YYYY-MM-DDTHH:mm:ss.sssZ".
  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."