Confluence User API

openapi: 3.2.0
info:
  title: Confluence Cloud REST API v2 User 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: User
  description: ''
paths:
  /users-bulk:
    post:
      tags:
      - User
      operationId: createBulkUserLookup
      summary: Create bulk user lookup using ids
      description: 'Returns user details for the ids provided in the request body.


        **Permissions required**:

        Permission to access the Confluence site (''Can use'' global permission).

        The user must be able to view user profiles in the Confluence site.'
      requestBody:
        $ref: '#/components/requestBodies/BulkUsersRequest'
      responses:
        '200':
          description: Returned if the user info is returned for the account IDs. `results` may be empty if no account IDs were found.
          content:
            application/json:
              schema:
                title: MultiEntityResult<User>
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  _links:
                    $ref: '#/components/schemas/MultiEntityLinks'
          headers:
            Link:
              schema:
                type: string
              description: 'This header contains URL(s) within angle brackets and a relation description for each URL, describing how the provided URL relates to the incoming request''s URL. Example response header format: <https://site.atlassian.net/wiki>; rel="base"`

                '
        '400':
          description: Returned if an invalid request is provided.
          content: {}
        '404':
          description: Returned if the calling user does not have permission to use Confluence or view user profiles.
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - read:user:confluence
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - read:user:confluence
      x-atlassian-connect-scope: READ
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
  /user/access/check-access-by-email:
    post:
      tags:
      - User
      operationId: checkAccessByEmail
      summary: Check site access for a list of emails
      description: 'Returns the list of emails from the input list that do not have access to site.


        **Permissions required**:

        Permission to access the Confluence site (''Can use'' global permission).'
      requestBody:
        $ref: '#/components/requestBodies/CheckAccessOrInviteByEmailRequest'
      responses:
        '200':
          description: Returns object with list of emails without access to site.
          content:
            application/json:
              schema:
                type: object
                properties:
                  emailsWithoutAccess:
                    type: array
                    items:
                      type: string
                    description: List of emails that do not have access to site.
                  invalidEmails:
                    type: array
                    items:
                      type: string
                    description: List of invalid emails provided in the request.
        '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 check access for emails on site.
        '503':
          description: Returned if API is disabled on site
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - read:configuration:confluence
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - read:configuration:confluence
      x-atlassian-connect-scope: NONE
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-experimental: true
  /user/access/invite-by-email:
    post:
      tags:
      - User
      operationId: inviteByEmail
      summary: Invite a list of emails to the site
      description: 'Invite a list of emails to the site.


        Ignores all invalid emails and no action is taken for the emails that already have access to the site.


        NOTE: This API is asynchronous and may take some time to complete.


        **Permissions required**:

        Permission to access the Confluence site (''Can use'' global permission).'
      requestBody:
        $ref: '#/components/requestBodies/CheckAccessOrInviteByEmailRequest'
      responses:
        '200':
          description: Returns object with list of emails without access to site.
          content: {}
        '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 check access for emails on site.
        '503':
          description: Returned if API is disabled on site
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - read:configuration:confluence
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - read:configuration:confluence
      x-atlassian-connect-scope: NONE
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-experimental: true
components:
  schemas:
    User:
      type: object
      properties:
        displayName:
          type: string
          description: Display name of the user.
        timeZone:
          type: string
          description: 'Time zone of the user. Depending on the user''s privacy

            setting, this may return null.'
        personalSpaceId:
          type: string
          description: Space ID of the user's personal space. Returns null, if no personal space for the user.
        isExternalCollaborator:
          type: boolean
          description: Whether the user is an external collaborator.
        accountStatus:
          $ref: '#/components/schemas/AccountStatus'
        accountId:
          type: string
          description: Account ID of the user.
        email:
          type: string
          description: The email address of the user. Depending on the user's privacy setting, this may return an empty string.
        accountType:
          $ref: '#/components/schemas/AccountType'
        publicName:
          type: string
          description: Public name of the user.
        profilePicture:
          $ref: '#/components/schemas/Icon'
    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.
    Icon:
      required:
      - path
      - isDefault
      type:
      - object
      - 'null'
      properties:
        path:
          type: string
        isDefault:
          type: boolean
      description: This object represents an icon. If used as a profilePicture, this may be returned as null, depending on the user's privacy setting.
    AccountStatus:
      enum:
      - active
      - inactive
      - closed
      - unknown
      type: string
      description: The account status of the user.
    AccountType:
      enum:
      - atlassian
      - app
      - customer
      - unknown
      type: string
      description: The account type of the user.
  requestBodies:
    CheckAccessOrInviteByEmailRequest:
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
            - emails
            properties:
              emails:
                description: List of emails to check access to site.
                type: array
                minItems: 1
                maxItems: 100
                items:
                  type: string
    BulkUsersRequest:
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
            - accountIds
            properties:
              accountIds:
                description: List of accountIds to retrieve user info for.
                type: array
                minItems: 1
                maxItems: 250
                items:
                  type: string
  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."