> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dfns.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Permission

> Retrieves a permission (role) by ID, including any pending change request.



## OpenAPI

````yaml /openapi.yaml get /permissions/{permissionId}
openapi: 3.1.0
info:
  version: 1.807.0
  title: Dfns
servers:
  - url: https://api.dfns.io
    description: Default - Europe
  - url: https://api.uae.dfns.io
    description: UAE
  - url: https://api.dfns.ninja
    description: <Deprecated> Staging
security: []
paths:
  /permissions/{permissionId}:
    get:
      tags:
        - Permissions
      summary: Get Permission
      description: >-
        Retrieves a permission (role) by ID, including any pending change
        request.
      parameters:
        - schema:
            type: string
            minLength: 1
            maxLength: 64
            description: >-
              ID of the permission (also referred to as "role" in the
              dashboard).
          required: true
          description: ID of the permission (also referred to as "role" in the dashboard).
          name: permissionId
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Permission'
                  - type: object
                    properties:
                      pendingChangeRequest:
                        type: object
                        properties:
                          id:
                            type: string
                            minLength: 1
                            maxLength: 64
                            pattern: ^cr-[a-z0-9]{5}-[a-z0-9]{5}-[a-z0-9]{14,16}$
                            description: ID of the change request.
                            example: cr-6uunn-bm6ja-f6rmod5kqrk5rbel
                          requester:
                            $ref: '#/components/schemas/ChangeRequestRequester'
                          status:
                            type: string
                            enum:
                              - Applied
                              - Failed
                              - Pending
                              - Rejected
                            description: Current status of the change request.
                          entityId:
                            type: string
                            description: ID of the entity being changed.
                          dateCreated:
                            type: string
                            format: date-time
                            description: >-
                              [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)
                              date (must be UTC). Date the change request was
                              created.
                            example: '2023-04-14T20:41:28.715Z'
                          dateResolved:
                            type: string
                            format: date-time
                            description: >-
                              [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)
                              date (must be UTC). Date the change request was
                              resolved.
                            example: '2023-04-14T20:41:28.715Z'
                          approvalId:
                            type: string
                            minLength: 1
                            maxLength: 64
                            pattern: ^ap-[a-z0-9]{5}-[a-z0-9]{5}-[a-z0-9]{14,16}$
                            example: ap-2a9in-tt2a1-983lho480p35ejd0
                          kind:
                            type: string
                            enum:
                              - Permission
                          operationKind:
                            type: string
                            enum:
                              - Update
                          body:
                            type: object
                            properties:
                              id:
                                type: string
                                minLength: 1
                                maxLength: 64
                                pattern: ^pm-[a-z0-9]{5}-[a-z0-9]{5}-[a-z0-9]{14,16}$
                                description: >-
                                  ID of the permission (also referred to as
                                  "role" in the dashboard).
                                example: pm-37vj4-jkr4l-lc9945spfftkne57
                              name:
                                type: string
                                description: Human-readable name of the permission (role).
                              status:
                                type: string
                                enum:
                                  - Active
                                description: Current status of the permission.
                              operations:
                                type: array
                                items:
                                  type: string
                                description: >-
                                  List of API operations this permission grants
                                  access to. See [Permissions
                                  List](https://docs.dfns.co/core-concepts/roles-and-permissions#list-of-permissions)
                                  for available operations.
                              isImmutable:
                                type: boolean
                                description: >-
                                  Whether this permission is system-managed and
                                  cannot be modified.
                              isArchived:
                                type: boolean
                                description: >-
                                  Whether this permission has been archived
                                  (soft-deleted).
                            required:
                              - id
                              - name
                              - status
                              - operations
                              - isImmutable
                              - isArchived
                            additionalProperties: false
                        required:
                          - id
                          - requester
                          - status
                          - entityId
                          - dateCreated
                          - kind
                          - operationKind
                          - body
                        additionalProperties: false
      security:
        - authenticationToken: []
components:
  schemas:
    Permission:
      type: object
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 64
          pattern: ^pm-[a-z0-9]{5}-[a-z0-9]{5}-[a-z0-9]{14,16}$
          description: ID of the permission (also referred to as "role" in the dashboard).
          example: pm-37vj4-jkr4l-lc9945spfftkne57
        name:
          type: string
          description: Human-readable name of the permission (role).
        operations:
          type: array
          items:
            type: string
          description: >-
            List of API operations this permission grants access to. See
            [Permissions
            List](https://docs.dfns.co/core-concepts/roles-and-permissions#list-of-permissions)
            for available operations.
        status:
          type: string
          enum:
            - Active
          description: Current status of the permission.
        isImmutable:
          type: boolean
          description: Whether this permission is system-managed and cannot be modified.
        isArchived:
          type: boolean
          description: Whether this permission has been archived (soft-deleted).
        dateCreated:
          type: string
          format: date-time
          description: >-
            [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date (must be
            UTC). Date the permission was created.
          example: '2023-04-14T20:41:28.715Z'
        dateUpdated:
          type: string
          format: date-time
          description: >-
            [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date (must be
            UTC). Date the permission was last updated.
          example: '2023-04-14T20:41:28.715Z'
      required:
        - id
        - name
        - operations
        - status
        - isImmutable
        - isArchived
        - dateCreated
        - dateUpdated
      additionalProperties: false
    ChangeRequestRequester:
      type: object
      properties:
        userId:
          type: string
        tokenId:
          type: string
        appId:
          type: string
      required:
        - userId
      description: The user who initiated the change request.
  securitySchemes:
    authenticationToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        **Bearer Token:** Used to authenticate API requests.

        More details how to generate the token: [Authentication
        flows](https://docs.dfns.co/api-reference/auth/login-flows)

````