Atlassian Groups API

openapi: 3.1.0
info:
  title: Atlassian Admin Account Groups API
  description: The Atlassian Admin API provides programmatic access to manage Atlassian organizations, users, domains, policies, and events. It enables administrators to automate organization management tasks, integrate with identity providers, and ensure appropriate access to Atlassian products.
  version: 1.0.0
  contact:
    name: Atlassian Developer
    url: https://developer.atlassian.com/cloud/admin/
  license:
    name: Atlassian Developer Terms
    url: https://developer.atlassian.com/platform/marketplace/atlassian-developer-terms/
  x-logo:
    url: https://wac-cdn.atlassian.com/assets/img/favicons/atlassian/favicon.png
servers:
- url: https://api.atlassian.com
  description: Atlassian Cloud API
security:
- bearerAuth: []
- oauth2: []
tags:
- name: Groups
  description: Manage groups within an organization.
paths:
  /v1/orgs/{orgId}/groups:
    get:
      operationId: getOrganizationGroups
      summary: Atlassian Get Organization Groups
      description: Returns a list of groups within the organization. Groups are used to organize users and assign collective permissions.
      tags:
      - Groups
      parameters:
      - $ref: '#/components/parameters/orgId'
      - name: cursor
        in: query
        description: Cursor for paginated results.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful response containing a paginated list of groups.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupPage'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Organization not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /repositories/{workspace}/{repo_slug}/permissions-config/groups:
    parameters:
    - name: repo_slug
      in: path
      description: 'This can either be the repository slug or the UUID of the repository,

        surrounded by curly-braces, for example: `{repository UUID}`.

        '
      required: true
      schema:
        type: string
    - name: workspace
      in: path
      description: 'This can either be the workspace ID (slug) or the workspace UUID

        surrounded by curly-braces, for example: `{workspace UUID}`.

        '
      required: true
      schema:
        type: string
    get:
      tags:
      - Groups
      description: This API operation retrieves a paginated list of all explicit group permissions that have been configured for a specific Bitbucket repository within a workspace. It returns permission configurations that directly grant access to groups at the repository level, as opposed to inherited or default permissions. The endpoint requires both the workspace identifier and repository slug to be specified in the URL path, and it returns details about which groups have been explicitly granted permissions to access or interact with the repository, along with the specific permission levels assigned to each group.
      summary: Atlassian List Explicit Group Permissions for Repository
      responses:
        '200':
          description: Paginated of explicit group permissions on the repository.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/paginated_repository_group_permissions'
              examples:
                paginated-repository-group-permissions:
                  $ref: '#/components/examples/paginated-repository-group-permissions'
        '401':
          description: The user couldn't be authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: The requesting user isn't an admin of the repository.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: One or both of the workspace and repository doesn't exist for the given identifiers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - oauth2:
        - repository:admin
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - read:repository:bitbucket
        - read:user:bitbucket
      operationId: listExplicitGroupPermissionsForRepository
      x-api-evangelist-processing:
        WriteDescription: true
        ChooseTags: true
        GenerateExampleFromOperationResponseSchema: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /repositories/{workspace}/{repo_slug}/permissions-config/groups/{group_slug}:
    parameters:
    - name: group_slug
      in: path
      description: Slug of the requested group.
      required: true
      schema:
        type: string
    - name: repo_slug
      in: path
      description: 'This can either be the repository slug or the UUID of the repository,

        surrounded by curly-braces, for example: `{repository UUID}`.

        '
      required: true
      schema:
        type: string
    - name: workspace
      in: path
      description: 'This can either be the workspace ID (slug) or the workspace UUID

        surrounded by curly-braces, for example: `{workspace UUID}`.

        '
      required: true
      schema:
        type: string
    delete:
      tags:
      - Groups
      description: This API operation removes an explicitly granted permission for a specific group from a Bitbucket repository. It targets a particular group identified by its slug within a repository (specified by workspace and repository slug) and deletes the permission configuration that was directly assigned to that group. This endpoint is useful when you need to revoke repository access rights that were previously granted to a team or group, requiring authentication and appropriate administrative privileges. The operation uses the DELETE HTTP method and returns a success status when the group permission is successfully removed from the repository's access control list.
      summary: Atlassian Delete an Explicit Group Permission for Repository
      responses:
        '204':
          description: Group permission deleted
        '401':
          description: The user couldn't be authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: The requesting user isn't an admin of the repository, or the authentication method was not via app password.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: The workspace does not exist, the repository does not exist, or the group does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - oauth2:
        - repository:admin
      - basic: []
      - api_key: []
      operationId: deleteAnExplicitGroupPermissionForRepository
      x-api-evangelist-processing:
        WriteDescription: true
        ChooseTags: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    get:
      tags:
      - Groups
      description: This API operation retrieves explicit permission settings assigned to a specific group for a given repository in Bitbucket. By providing the workspace identifier, repository slug, and group slug as path parameters, it returns detailed information about the permission level that has been directly granted to that group for accessing and managing the specified repository. This is useful for administrators who need to audit or verify group-level access controls, as it shows only explicitly configured permissions rather than inherited or default permissions. The response typically includes the group's identifier, the permission level (such as read, write, or admin), and potentially additional metadata about when and how the permission was assigned.
      summary: Atlassian Get an Explicit Group Permission for Repository
      responses:
        '200':
          description: Group permission for group slug and repository
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/repository_group_permission'
              examples:
                repository-group-permission:
                  $ref: '#/components/examples/repository-group-permission'
        '401':
          description: The user couldn't be authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: The requesting user isn't an admin of the repository.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: The given user, workspace, and/or repository could not be found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - oauth2:
        - repository:admin
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - read:repository:bitbucket
        - read:user:bitbucket
      operationId: getAnExplicitGroupPermissionForRepository
      x-api-evangelist-processing:
        WriteDescription: true
        ChooseTags: true
        GenerateExampleFromOperationResponseSchema: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      tags:
      - Groups
      description: This API operation updates the explicit permission level for a specific group on a Bitbucket repository within a workspace. By sending a PUT request to the endpoint with the workspace identifier, repository slug, and group slug, administrators can modify the access rights granted to that group for the specified repository. The operation allows you to change permission levels such as read, write, or admin access for the group, providing fine-grained control over repository access management. This is particularly useful for managing team permissions and ensuring that user groups have appropriate access levels based on their roles and responsibilities within the organization.
      summary: Atlassian Update an Explicit Group Permission for Repository
      responses:
        '200':
          description: Group permission updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/repository_group_permission'
              examples:
                repository-group-permission_2:
                  $ref: '#/components/examples/repository-group-permission_2'
        '400':
          description: No permission value was provided or the value is invalid(not one of read, write, or admin)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: The user couldn't be authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '402':
          description: You have reached your plan's user limit and must upgrade before giving access to additional users.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: The requesting user isn't an admin of the repository, or the authentication method was not via app password.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: The workspace does not exist, the repository does not exist, or the group does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      requestBody:
        $ref: '#/components/requestBodies/BitbucketAppsPermissionsSerializersRepoPermissionUpdateSchema'
      security:
      - oauth2:
        - repository:admin
      - basic: []
      - api_key: []
      operationId: updateAnExplicitGroupPermissionForRepository
      x-api-evangelist-processing:
        WriteDescription: true
        ChooseTags: true
        GenerateExampleFromOperationResponseSchema: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /workspaces/{workspace}/projects/{project_key}/permissions-config/groups:
    parameters:
    - name: project_key
      in: path
      description: 'The project in question. This is the actual key assigned to the project.

        '
      required: true
      schema:
        type: string
    - name: workspace
      in: path
      description: 'This can either be the workspace ID (slug) or the workspace UUID

        surrounded by curly-braces, for example: `{workspace UUID}`.

        '
      required: true
      schema:
        type: string
    get:
      tags:
      - Groups
      description: This API endpoint retrieves a paginated list of explicit group permissions that have been directly granted to groups for a specific project within a Bitbucket workspace. By making a GET request to this endpoint with the workspace identifier and project key as path parameters, you can view all groups that have been explicitly assigned permissions to the project, along with their corresponding permission levels. This is useful for auditing access control, understanding who has what level of access to a project, and managing team permissions. The response excludes inherited permissions and only shows permissions that have been directly configured at the project level for groups, making it easier to track and manage explicit access grants without the noise of inherited permissions from workspace-level settings.
      summary: Atlassian List Explicit Group Permissions for a Project
      responses:
        '200':
          description: Paginated list of project group permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/paginated_project_group_permissions'
              examples:
                paginated-project-group-permissions:
                  $ref: '#/components/examples/paginated-project-group-permissions'
        '401':
          description: The user couldn't be authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: The user doesn't have admin access to the project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: One or both of the workspace and project don't exist for the given identifiers or the requesting user is not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - oauth2:
        - project:admin
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - read:project:bitbucket
        - read:user:bitbucket
      operationId: atlassianListExplicitGroupPermissionsForAProject
      x-api-evangelist-processing:
        WriteDescription: true
        ChooseTags: true
        GenerateExampleFromOperationResponseSchema: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /workspaces/{workspace}/projects/{project_key}/permissions-config/groups/{group_slug}:
    parameters:
    - name: group_slug
      in: path
      description: Slug of the requested group.
      required: true
      schema:
        type: string
    - name: project_key
      in: path
      description: 'The project in question. This is the actual key assigned to the project.

        '
      required: true
      schema:
        type: string
    - name: workspace
      in: path
      description: 'This can either be the workspace ID (slug) or the workspace UUID

        surrounded by curly-braces, for example: `{workspace UUID}`.

        '
      required: true
      schema:
        type: string
    delete:
      tags:
      - Groups
      description: This API operation removes an explicitly granted group permission from a specific project within a Bitbucket workspace by sending a DELETE request to the designated endpoint, which requires the workspace identifier, project key, and group slug as path parameters to target the exact permission configuration that needs to be revoked, effectively revoking that group's direct access rights to the project while potentially leaving inherited or other permission types intact, allowing workspace administrators to maintain granular control over project-level access by selectively removing group permissions without affecting individual user permissions or other security settings associated with the project.
      summary: Atlassian Delete an Explicit Group Permission for a Project
      responses:
        '204':
          description: The project group permission was deleted and no content returned.
        '401':
          description: The user couldn't be authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: The requesting user isn't an admin of the project, or the authentication method was not via app password.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: One or more of the workspace, project, and group doesn't exist                               for the given identifiers or the requesting user is not                               authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - oauth2:
        - project:admin
      - basic: []
      - api_key: []
      operationId: atlassianDeleteAnExplicitGroupPermissionForAProject
      x-api-evangelist-processing:
        WriteDescription: true
        ChooseTags: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    get:
      tags:
      - Groups
      description: This API operation retrieves the explicit permission settings assigned to a specific group for a particular project within a Bitbucket workspace. By providing the workspace identifier, project key, and group slug as path parameters, the endpoint returns detailed information about what access level and permissions have been directly granted to that group for the specified project. This is useful for auditing group-level permissions, understanding access control configurations, and managing team-based security policies within Bitbucket projects, as it shows only the permissions explicitly set for the group rather than inherited or default permissions.
      summary: Atlassian Get an Explicit Group Permission for a Project
      responses:
        '200':
          description: Project group permission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/project_group_permission'
              examples:
                project-group-permission:
                  $ref: '#/components/examples/project-group-permission'
        '401':
          description: The user couldn't be authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: The user doesn't have admin access to the project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: One or more of the workspace, project, and group doesn't exist                               for the given identifiers or the requesting user is not                               authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - oauth2:
        - project:admin
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - read:project:bitbucket
        - read:user:bitbucket
      operationId: atlassianGetAnExplicitGroupPermissionForAProject
      x-api-evangelist-processing:
        WriteDescription: true
        ChooseTags: true
        GenerateExampleFromOperationResponseSchema: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      tags:
      - Groups
      description: This API operation updates the explicit permissions assigned to a specific group within a Bitbucket project. By making a PUT request to the endpoint with the workspace identifier, project key, and group slug, administrators can modify the access level granted to that group for the specified project. This allows for fine-grained control over project permissions by adjusting what actions members of a particular group can perform, such as read, write, or admin privileges. The operation requires proper authentication and administrative rights within the workspace, and it directly modifies the existing permission configuration rather than creating a new one, making it useful for maintaining and adjusting team access controls as project requirements evolve.
      summary: Atlassian Update an Explicit Group Permission for a Project
      responses:
        '200':
          description: Project group permission updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/project_group_permission'
              examples:
                project-group-permission_2:
                  $ref: '#/components/examples/project-group-permission_2'
        '400':
          description: No permission value was provided or the value is invalid(not one of read, write, create-repo, or admin).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: The user couldn't be authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '402':
          description: You have reached your plan's user limit and must upgrade before giving access to additional users.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: The requesting user isn't an admin of the project, or the authentication method was not via app password.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: One or more of the workspace, project, and group doesn't exist                               for the given identifiers or the requesting user is not                               authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      requestBody:
        $ref: '#/components/requestBodies/bitbucket.apps.permissions.serializers.ProjectPermissionUpdateSchema'
      security:
      - oauth2:
        - project:admin
      - basic: []
      - api_key: []
      operationId: atlassianUpdateAnExplicitGroupPermissionForAProject
      x-api-evangelist-processing:
        WriteDescription: true
        ChooseTags: true
        GenerateExampleFromOperationResponseSchema: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /wiki/rest/api/content/{id}/restriction/byOperation/{operationKey}/group/{groupName}:
    get:
      tags:
      - Groups
      summary: Atlassian Get Content Restriction Status for Group
      deprecated: true
      description: 'The Atlassian Confluence Content API endpoint `/wiki/rest/api/content/{id}/restriction/byOperation/{operationKey}/group/{groupName}` using the GET method retrieves the restriction status for a specific group on a particular piece of content. This operation allows administrators and authorized users to check whether a designated group has restrictions applied for a specific operation (such as read or update) on content identified by its unique ID. The endpoint requires three path parameters: the content ID, the operation key that defines the type of action being restricted, and the group name for which to check restrictions. The response returns details about whether the specified group is restricted from performing the given operation on the content, helping manage fine-grained access control within Confluence spaces and pages.'
      operationId: getContentRestrictionStatusForGroup
      parameters:
      - name: id
        in: path
        description: The ID of the content that the restriction applies to.
        required: true
        schema:
          type: string
      - name: operationKey
        in: path
        description: The operation that the restriction applies to.
        required: true
        schema:
          type: string
          enum:
          - read
          - update
      - name: groupName
        in: path
        description: 'The name of the group to be queried for whether the content restriction

          applies to it.'
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'Returns true if the content restriction applies to the group. The response

            will not return a response body.'
          content: {}
        '400':
          description: 'Returned if;


            - Group name is missing'
          content: {}
        '404':
          description: 'Returned if;


            - There is no content with the given ID.

            - The calling user does not have permission to view the content.

            - An invalid operation or group is specified.'
          content: {}
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - read:confluence-content.all
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - read:confluence-content.all
      - scheme: oAuthDefinitions
        state: Beta
        scopes:
        - read:content.restriction:confluence
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: false
      x-atlassian-connect-scope: READ
      x-api-evangelist-processing:
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        WriteDescription: true
        ChooseTags: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      tags:
      - Groups
      summary: Atlassian Add Group to Content Restriction
      deprecated: true
      description: 'The PUT operation on the Atlassian Confluence Content API endpoint `/wiki/rest/api/content/{id}/restriction/byOperation/{operationKey}/group/{groupName}` adds a specified group to an existing content restriction for a particular operation type. This allows administrators to grant a group access to perform specific operations (such as read, update, or delete) on restricted Confluence content by including the group in the restriction''s allowed list. The endpoint requires three path parameters: the content ID identifying the specific page or blog post, the operation key specifying the type of operation being restricted (like ''read'' or ''update''), and the group name identifying which user group should be granted access. This operation is essential for managing collaborative permissions and implementing fine-grained access control within Confluence spaces, enabling teams to secure sensitive content while selectively allowing specific groups to interact with it based on their operational needs.'
      operationId: addGroupToContentRestriction
      parameters:
      - name: id
        in: path
        description: The ID of the content that the restriction applies to.
        required: true
        schema:
          type: string
      - name: operationKey
        in: path
        description: The operation that the restriction applies to.
        required: true
        schema:
          type: string
          enum:
          - read
          - update
      - name: groupName
        in: path
        description: The name of the group to add to the content restriction.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'Returned if the group is added to the content restriction. The response

            body will be empty.'
          content: {}
        '404':
          description: 'Returned if;


            - There is no content with the given ID.

            - The calling user does not have permission to view the content.

            - An invalid operation or group is specified.'
          content: {}
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - write:confluence-content
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - write:confluence-content
      - scheme: oAuthDefinitions
        state: Beta
        scopes:
        - write:content.restriction:confluence
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: false
      x-atlassian-connect-scope: WRITE
      x-api-evangelist-processing:
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        WriteDescription: true
        ChooseTags: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      tags:
      - Groups
      summary: Atlassian Remove Group From Content Restriction
      deprecated: true
      description: This API operation removes a specific group from content restrictions for a given operation on a Confluence page or blog post. By sending a DELETE request to this endpoint with the content ID, operation key (such as 'read' or 'update'), and group name, administrators can revoke the specified group's access permissions for that particular operation on the content. This is useful for managing granular access control when you need to remove a group's ability to perform specific actions on restricted content without affecting other groups or individual user restrictions that may be in place.
      operationId: removeGroupFromContentRestriction
      parameters:
      - name: id
        in: path
        description: The ID of the content that the restriction applies to.
        required: true
        schema:
          type: string
      - name: operationKey
        in: path
        description: The operation that the restriction applies to.
        required: true
        schema:
          type: string
          enum:
          - read
          - update
      - name: groupName
        in: path
        description: The name of the group to remove from the content restriction.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'Returned if the group is removed from the content restriction. The response

            body will be empty.'
          content: {}
        '404':
          description: 'Returned if;


            - There is no content with the given ID.

            - The calling user does not have permission to view the content.

            - The restriction to be deleted does not exist.'
          content: {}
      security:
      - basicAuth: []
      - oAuthDefinitions:
  

# --- truncated at 32 KB (109 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/atlassian/refs/heads/main/openapi/atlassian-groups-api-openapi.yml