Atlassian Project Permission Schemes API

openapi: 3.1.0
info:
  title: Atlassian Admin Account Project Permission Schemes 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: Project Permission Schemes
paths:
  /rest/api/3/project/{projectKeyOrId}/issuesecuritylevelscheme:
    get:
      deprecated: false
      description: Returns the [issue security scheme](https://confluence.atlassian.com/x/J4lKLg) associated with the project.<br><br>**[Permissions](#permissions) required:** *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg) or the *Administer Projects* [project permission](https://confluence.atlassian.com/x/yodKLg).
      operationId: atlassianGetprojectissuesecurityscheme
      parameters:
      - description: The project ID or project key (case sensitive).
        in: path
        name: projectKeyOrId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example: '{"defaultSecurityLevelId":10021,"description":"Description for the default issue security scheme","id":10000,"levels":[{"description":"Only the reporter and internal staff can see this issue.","id":"10021","name":"Reporter Only","self":"https://your-domain.atlassian.net/rest/api/3/securitylevel/10021"}],"name":"Default Issue Security Scheme","self":"https://your-domain.atlassian.net/rest/api/3/issuesecurityschemes/10000"}'
              schema:
                $ref: '#/components/schemas/SecurityScheme'
          description: Returned if the request is successful.
        '400':
          description: Returned if the request is invalid.
        '401':
          description: Returned if the authentication credentials are incorrect or missing.
        '403':
          description: Returned if the project is visible to the user but the user doesn't have administrative permissions.
        '404':
          description: Returned if the project is not found or the user does not have permission to view it.
      security:
      - basicAuth: []
      - OAuth2:
        - read:jira-work
      summary: Atlassian Get Project Issue Security Scheme
      tags:
      - Project Permission Schemes
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-atlassian-oauth2-scopes:
      - scheme: OAuth2
        scopes:
        - read:jira-work
        state: Current
      - scheme: OAuth2
        scopes:
        - read:issue-security-level:jira
        - read:issue-security-scheme:jira
        state: Beta
      x-atlassian-connect-scope: READ
  /rest/api/3/project/{projectKeyOrId}/permissionscheme:
    get:
      deprecated: false
      description: Gets the [permission scheme](https://confluence.atlassian.com/x/yodKLg) associated with the project.<br><br>**[Permissions](#permissions) required:** *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg) or *Administer projects* [project permission](https://confluence.atlassian.com/x/yodKLg).
      operationId: atlassianGetassignedpermissionscheme
      parameters:
      - description: The project ID or project key (case sensitive).
        in: path
        name: projectKeyOrId
        required: true
        schema:
          type: string
      - description: "Use [expand](#expansion) to include additional information in the response. This parameter accepts a comma-separated list. Note that permissions are included when you specify any value. Expand options include:\n\n *  `all` Returns all expandable information.\n *  `field` Returns information about the custom field granted the permission.\n *  `group` Returns information about the group that is granted the permission.\n *  `permissions` Returns all permission grants for each permission scheme.\n *  `projectRole` Returns information about the project role granted the permission.\n *  `user` Returns information about the user who is granted the permission."
        in: query
        name: expand
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example: '{"description":"description","id":10000,"name":"Example permission scheme","self":"https://your-domain.atlassian.net/rest/api/3/permissionscheme/10000"}'
              schema:
                $ref: '#/components/schemas/PermissionScheme'
          description: Returned if the request is successful.
        '401':
          description: Returned if the authentication credentials are incorrect or missing.
        '403':
          description: Returned if the user does not have permission to view the project's configuration.
        '404':
          description: Returned if the project is not found or the user does not have permission to view the project.
      security:
      - basicAuth: []
      - OAuth2:
        - read:jira-work
      summary: Atlassian Get Assigned Permission Scheme
      tags:
      - Project Permission Schemes
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-atlassian-oauth2-scopes:
      - scheme: OAuth2
        scopes:
        - read:jira-work
        state: Current
      - scheme: OAuth2
        scopes:
        - read:application-role:jira
        - read:field:jira
        - read:group:jira
        - read:permission-scheme:jira
        - read:permission:jira
        - read:project-role:jira
        - read:user:jira
        - read:avatar:jira
        - read:project-category:jira
        - read:project:jira
        state: Beta
      x-atlassian-connect-scope: READ
    put:
      deprecated: false
      description: Assigns a permission scheme with a project. See [Managing project permissions](https://confluence.atlassian.com/x/yodKLg) for more information about permission schemes.<br><br>**[Permissions](#permissions) required:** *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg)
      operationId: atlassianAssignpermissionscheme
      parameters:
      - description: The project ID or project key (case sensitive).
        in: path
        name: projectKeyOrId
        required: true
        schema:
          type: string
      - description: "Use [expand](#expansion) to include additional information in the response. This parameter accepts a comma-separated list. Note that permissions are included when you specify any value. Expand options include:\n\n *  `all` Returns all expandable information.\n *  `field` Returns information about the custom field granted the permission.\n *  `group` Returns information about the group that is granted the permission.\n *  `permissions` Returns all permission grants for each permission scheme.\n *  `projectRole` Returns information about the project role granted the permission.\n *  `user` Returns information about the user who is granted the permission."
        in: query
        name: expand
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              id: 10000
            schema:
              $ref: '#/components/schemas/IdBean'
        required: true
      responses:
        '200':
          content:
            application/json:
              example: '{"description":"description","id":10000,"name":"Example permission scheme","self":"https://your-domain.atlassian.net/rest/api/3/permissionscheme/10000"}'
              schema:
                $ref: '#/components/schemas/PermissionScheme'
          description: Returned if the request is successful.
        '401':
          description: Returned if the authentication credentials are incorrect or missing.
        '403':
          description: "Returned if:\n\n *  the user does not have the necessary permission to edit the project's configuration.\n *  the Jira instance is Jira Core Free or Jira Software Free. Permission schemes cannot be assigned to projects on free plans."
        '404':
          description: Returned if the project or permission scheme is not found.
      security:
      - basicAuth: []
      - OAuth2:
        - manage:jira-project
      summary: Atlassian Assign Permission Scheme
      tags:
      - Project Permission Schemes
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-atlassian-oauth2-scopes:
      - scheme: OAuth2
        scopes:
        - manage:jira-project
        state: Current
      - scheme: OAuth2
        scopes:
        - read:application-role:jira
        - read:field:jira
        - read:group:jira
        - read:permission-scheme:jira
        - read:permission:jira
        - read:project-role:jira
        - read:user:jira
        - write:project:jira
        - read:avatar:jira
        - read:project-category:jira
        - read:project:jira
        state: Beta
      x-atlassian-connect-scope: PROJECT_ADMIN
  /rest/api/3/project/{projectKeyOrId}/securitylevel:
    get:
      deprecated: false
      description: Returns all [issue security](https://confluence.atlassian.com/x/J4lKLg) levels for the project that the user has access to.<br><br>This operation can be accessed anonymously.<br><br>**[Permissions](#permissions) required:** *Browse projects* [global permission](https://confluence.atlassian.com/x/x4dKLg) for the project, however, issue security levels are only returned for authenticated user with *Set Issue Security* [global permission](https://confluence.atlassian.com/x/x4dKLg) for the project.
      operationId: atlassianGetsecuritylevelsforproject
      parameters:
      - description: The project ID or project key (case sensitive).
        in: path
        name: projectKeyOrId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example: '{"levels":[{"description":"Only the reporter and internal staff can see this issue.","id":"100000","name":"Reporter Only","self":"https://your-domain.atlassian.net/rest/api/3/securitylevel/100000"},{"description":"Only internal staff can see this issue.","id":"100001","name":"Staff Only","self":"https://your-domain.atlassian.net/rest/api/3/securitylevel/100001"}]}'
              schema:
                $ref: '#/components/schemas/ProjectIssueSecurityLevels'
          description: Returned if the request is successful.
        '404':
          description: Returned if the project is not found or the user does not have permission to view it.
      security:
      - basicAuth: []
      - OAuth2:
        - read:jira-work
      - {}
      summary: Atlassian Get Project Issue Security Levels
      tags:
      - Project Permission Schemes
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: false
      x-atlassian-oauth2-scopes:
      - scheme: OAuth2
        scopes:
        - read:jira-work
        state: Current
      - scheme: OAuth2
        scopes:
        - read:issue-security-level:jira
        state: Beta
      x-atlassian-connect-scope: READ
components:
  schemas:
    PermissionHolder:
      additionalProperties: false
      description: Details of a user, group, field, or project role that holds a permission. See [Holder object](../api-group-permission-schemes/#holder-object) in *Get all permission schemes* for more information.
      properties:
        expand:
          description: Expand options that include additional permission holder details in the response.
          readOnly: true
          type: string
        parameter:
          description: As a group's name can change, use of `value` is recommended. The identifier associated withthe `type` value that defines the holder of the permission.
          type: string
        type:
          description: The type of permission holder.
          type: string
        value:
          description: The identifier associated with the `type` value that defines the holder of the permission.
          type: string
      required:
      - type
      type: object
    Scope:
      additionalProperties: true
      description: The projects the item is associated with. Indicated for items associated with [next-gen projects](https://confluence.atlassian.com/x/loMyO).
      properties:
        project:
          allOf:
          - $ref: '#/components/schemas/ProjectDetails'
          description: The project the item has scope in.
          readOnly: true
        type:
          description: The type of scope.
          enum:
          - PROJECT
          - TEMPLATE
          readOnly: true
          type: string
      type: object
    ProjectIssueSecurityLevels:
      additionalProperties: false
      description: List of issue level security items in a project.
      properties:
        levels:
          description: Issue level security items list.
          items:
            $ref: '#/components/schemas/SecurityLevel'
          readOnly: true
          type: array
      required:
      - levels
      type: object
    UpdatedProjectCategory:
      additionalProperties: false
      description: A project category.
      properties:
        description:
          description: The name of the project category.
          readOnly: true
          type: string
        id:
          description: The ID of the project category.
          readOnly: true
          type: string
        name:
          description: The description of the project category.
          readOnly: true
          type: string
        self:
          description: The URL of the project category.
          readOnly: true
          type: string
      type: object
    IdBean:
      additionalProperties: false
      properties:
        id:
          description: The ID of the permission scheme to associate with the project. Use the [Get all permission schemes](#api-rest-api-3-permissionscheme-get) resource to get a list of permission scheme IDs.
          format: int64
          type: integer
      required:
      - id
      type: object
    SecurityLevel:
      additionalProperties: false
      description: Details of an issue level security item.
      properties:
        description:
          description: The description of the issue level security item.
          readOnly: true
          type: string
        id:
          description: The ID of the issue level security item.
          readOnly: true
          type: string
        isDefault:
          description: Whether the issue level security item is the default.
          readOnly: true
          type: boolean
        issueSecuritySchemeId:
          description: The ID of the issue level security scheme.
          readOnly: true
          type: string
        name:
          description: The name of the issue level security item.
          readOnly: true
          type: string
        self:
          description: The URL of the issue level security item.
          readOnly: true
          type: string
      type: object
    SecurityScheme:
      additionalProperties: false
      description: Details about a security scheme.
      properties:
        defaultSecurityLevelId:
          description: The ID of the default security level.
          format: int64
          readOnly: true
          type: integer
        description:
          description: The description of the issue security scheme.
          readOnly: true
          type: string
        id:
          description: The ID of the issue security scheme.
          format: int64
          readOnly: true
          type: integer
        levels:
          items:
            $ref: '#/components/schemas/SecurityLevel'
          type: array
        name:
          description: The name of the issue security scheme.
          readOnly: true
          type: string
        self:
          description: The URL of the issue security scheme.
          readOnly: true
          type: string
      type: object
    PermissionGrant:
      additionalProperties: true
      description: Details about a permission granted to a user or group.
      properties:
        holder:
          allOf:
          - $ref: '#/components/schemas/PermissionHolder'
          description: The user or group being granted the permission. It consists of a `type`, a type-dependent `parameter` and a type-dependent `value`. See [Holder object](../api-group-permission-schemes/#holder-object) in *Get all permission schemes* for more information.
        id:
          description: The ID of the permission granted details.
          format: int64
          readOnly: true
          type: integer
        permission:
          description: The permission to grant. This permission can be one of the built-in permissions or a custom permission added by an app. See [Built-in permissions](../api-group-permission-schemes/#built-in-permissions) in *Get all permission schemes* for more information about the built-in permissions. See the [project permission](https://developer.atlassian.com/cloud/jira/platform/modules/project-permission/) and [global permission](https://developer.atlassian.com/cloud/jira/platform/modules/global-permission/) module documentation for more information about custom permissions.
          type: string
        self:
          description: The URL of the permission granted details.
          format: uri
          readOnly: true
          type: string
      type: object
    PermissionScheme:
      additionalProperties: true
      description: Details of a permission scheme.
      properties:
        description:
          description: A description for the permission scheme.
          type: string
        expand:
          description: The expand options available for the permission scheme.
          readOnly: true
          type: string
        id:
          description: The ID of the permission scheme.
          format: int64
          readOnly: true
          type: integer
        name:
          description: The name of the permission scheme. Must be unique.
          type: string
        permissions:
          description: The permission scheme to create or update. See [About permission schemes and grants](../api-group-permission-schemes/#about-permission-schemes-and-grants) for more information.
          items:
            $ref: '#/components/schemas/PermissionGrant'
          type: array
        scope:
          allOf:
          - $ref: '#/components/schemas/Scope'
          description: The scope of the permission scheme.
        self:
          description: The URL of the permission scheme.
          format: uri
          readOnly: true
          type: string
      required:
      - name
      type: object
    AvatarUrlsBean:
      additionalProperties: false
      properties:
        16x16:
          description: The URL of the item's 16x16 pixel avatar.
          format: uri
          type: string
        24x24:
          description: The URL of the item's 24x24 pixel avatar.
          format: uri
          type: string
        32x32:
          description: The URL of the item's 32x32 pixel avatar.
          format: uri
          type: string
        48x48:
          description: The URL of the item's 48x48 pixel avatar.
          format: uri
          type: string
      type: object
    ProjectDetails:
      additionalProperties: false
      description: Details about a project.
      properties:
        avatarUrls:
          allOf:
          - $ref: '#/components/schemas/AvatarUrlsBean'
          description: The URLs of the project's avatars.
          readOnly: true
        id:
          description: The ID of the project.
          type: string
        key:
          description: The key of the project.
          readOnly: true
          type: string
        name:
          description: The name of the project.
          readOnly: true
          type: string
        projectCategory:
          allOf:
          - $ref: '#/components/schemas/UpdatedProjectCategory'
          description: The category the project belongs to.
          readOnly: true
        projectTypeKey:
          description: The [project type](https://confluence.atlassian.com/x/GwiiLQ#Jiraapplicationsoverview-Productfeaturesandprojecttypes) of the project.
          enum:
          - software
          - service_desk
          - business
          readOnly: true
          type: string
        self:
          description: The URL of the project details.
          readOnly: true
          type: string
        simplified:
          description: Whether or not the project is simplified.
          readOnly: true
          type: boolean
      type: object
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: Use an Atlassian API key as a Bearer token. Create API keys at https://admin.atlassian.com.
    oauth2:
      type: oauth2
      description: OAuth 2.0 authorization for Atlassian Cloud APIs.
      flows:
        authorizationCode:
          authorizationUrl: https://auth.atlassian.com/authorize
          tokenUrl: https://auth.atlassian.com/oauth/token
          scopes:
            read:org:admin: Read organization information.
            write:org:admin: Modify organization settings.
            read:user:admin: Read user information.
            write:user:admin: Modify user accounts.
            read:policy:admin: Read organization policies.
            write:policy:admin: Modify organization policies.
            read:event:admin: Read organization events.
externalDocs:
  description: Atlassian Admin REST API Documentation
  url: https://developer.atlassian.com/cloud/admin/organization/rest/intro/