openapi: 3.1.1
info:
  title: WorkOS admin-portal permissions API
  description: WorkOS REST API
  version: '1.0'
  contact:
    name: WorkOS
    url: https://workos.com
    email: support@workos.com
  license:
    name: MIT
    url: https://opensource.org/license/MIT
servers:
- url: https://api.workos.com
  description: Production
- url: https://api.workos-test.com
  description: Staging
security:
- bearer: []
tags:
- name: permissions
  description: Manage permissions.
  x-displayName: Permissions
paths:
  /authorization/permissions:
    get:
      description: Get a list of all permissions in your WorkOS environment.
      operationId: AuthorizationPermissionsController_list
      parameters:
      - name: before
        required: false
        in: query
        description: An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `before="obj_123"` to fetch a new batch of objects before `"obj_123"`.
        schema:
          example: xxx_01HXYZ123456789ABCDEFGHIJ
          type: string
      - name: after
        required: false
        in: query
        description: An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `after="obj_123"` to fetch a new batch of objects after `"obj_123"`.
        schema:
          example: xxx_01HXYZ987654321KJIHGFEDCBA
          type: string
      - name: limit
        required: false
        in: query
        description: Upper limit on the number of objects to return, between `1` and `100`.
        schema:
          minimum: 1
          maximum: 100
          default: 10
          example: 10
          type: integer
      - name: order
        required: false
        in: query
        description: Order the results by the creation time. Supported values are `"asc"` (ascending), `"desc"` (descending), and `"normal"` (descending with reversed cursor semantics where `before` fetches older records and `after` fetches newer records). Defaults to descending.
        schema:
          $ref: '#/components/schemas/PaginationOrder'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationPermissionList'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: A human-readable description of the error.
                    example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.'
                required:
                - message
      summary: List Permissions
      tags:
      - permissions
    post:
      description: Create a new permission in your WorkOS environment. The permission can then be assigned to environment roles and custom roles.
      operationId: AuthorizationPermissionsController_create
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAuthorizationPermissionDto'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    description: Distinguishes the Permission object.
                    const: permission
                  id:
                    type: string
                    description: Unique identifier of the Permission.
                    example: perm_01HXYZ123456789ABCDEFGHIJ
                  slug:
                    type: string
                    description: A unique key to reference the permission. Must be lowercase and contain only letters, numbers, hyphens, underscores, colons, periods, and asterisks.
                    example: documents:read
                  name:
                    type: string
                    description: A descriptive name for the Permission.
                    example: View Documents
                  description:
                    type:
                    - string
                    - 'null'
                    description: An optional description of the Permission.
                    example: Allows viewing document contents
                  system:
                    type: boolean
                    description: Whether the permission is a system permission. System permissions are managed by WorkOS and cannot be deleted.
                    example: false
                  resource_type_slug:
                    type: string
                    description: The slug of the resource type associated with the permission.
                    example: document
                  created_at:
                    format: date-time
                    type: string
                    description: An ISO 8601 timestamp.
                    example: '2026-01-15T12:00:00.000Z'
                  updated_at:
                    format: date-time
                    type: string
                    description: An ISO 8601 timestamp.
                    example: '2026-01-15T12:00:00.000Z'
                required:
                - object
                - id
                - slug
                - name
                - description
                - system
                - resource_type_slug
                - created_at
                - updated_at
                x-inline-with-overrides: true
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: The error code identifying the type of error.
                    example: bad_request
                    const: bad_request
                  message:
                    type: string
                    description: A human-readable description of the error.
                    example: Request could not be processed.
                required:
                - code
                - message
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: A human-readable description of the error.
                    example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.'
                required:
                - message
        '409':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: The error code identifying the type of error.
                    example: permission_slug_conflict
                    const: permission_slug_conflict
                  message:
                    type: string
                    description: A human-readable description of the error.
                    example: Request could not be processed.
                required:
                - code
                - message
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: A human-readable description of the error.
                    example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.'
                required:
                - message
      summary: Create a Permission
      tags:
      - permissions
  /authorization/permissions/{slug}:
    get:
      description: Retrieve a permission by its unique slug.
      operationId: AuthorizationPermissionsController_find
      parameters:
      - name: slug
        required: true
        in: path
        description: A unique key to reference the permission. Must be lowercase and contain only letters, numbers, hyphens, underscores, colons, periods, and asterisks.
        schema:
          example: documents:read
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationPermission'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: A human-readable description of the error.
                    example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.'
                required:
                - message
      summary: Get a Permission
      tags:
      - permissions
    patch:
      description: Update an existing permission. Only the fields provided in the request body will be updated.
      operationId: AuthorizationPermissionsController_update
      parameters:
      - name: slug
        required: true
        in: path
        description: A unique key to reference the permission. Must be lowercase and contain only letters, numbers, hyphens, underscores, colons, periods, and asterisks.
        schema:
          example: documents:read
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAuthorizationPermissionDto'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationPermission'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: A human-readable description of the error.
                    example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.'
                required:
                - message
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: A human-readable description of the error.
                    example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.'
                required:
                - message
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: A human-readable description of the error.
                    example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.'
                required:
                - message
      summary: Update a Permission
      tags:
      - permissions
    delete:
      description: Delete an existing permission. System permissions cannot be deleted.
      operationId: AuthorizationPermissionsController_delete
      parameters:
      - name: slug
        required: true
        in: path
        description: A unique key to reference the permission. Must be lowercase and contain only letters, numbers, hyphens, underscores, colons, periods, and asterisks.
        schema:
          example: documents:read
          type: string
      responses:
        '204':
          description: No Content
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: A human-readable description of the error.
                    example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.'
                required:
                - message
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: A human-readable description of the error.
                    example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.'
                required:
                - message
      summary: Delete a Permission
      tags:
      - permissions
components:
  schemas:
    UpdateAuthorizationPermissionDto:
      type: object
      properties:
        name:
          type: string
          maxLength: 48
          description: A descriptive name for the Permission.
          example: View Documents
        description:
          type:
          - string
          - 'null'
          maxLength: 150
          description: An optional description of the Permission.
          example: Allows viewing document contents
    AuthorizationPermissionList:
      type: object
      properties:
        object:
          type: string
          description: Indicates this is a list response.
          const: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/AuthorizationPermission'
          description: The list of records for the current page.
        list_metadata:
          type: object
          properties:
            before:
              type:
              - string
              - 'null'
              description: An object ID that defines your place in the list. When the ID is not present, you are at the start of the list.
              example: perm_01HXYZ123456789ABCDEFGHIJ
            after:
              type:
              - string
              - 'null'
              description: An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
              example: perm_01HXYZ987654321KJIHGFEDCBA
          required:
          - before
          - after
          description: Pagination cursors for navigating between pages of results.
      required:
      - object
      - data
      - list_metadata
    PaginationOrder:
      type: string
      enum:
      - normal
      - desc
      - asc
      example: desc
      default: desc
    AuthorizationPermission:
      type: object
      properties:
        object:
          type: string
          description: Distinguishes the Permission object.
          const: permission
        id:
          type: string
          description: Unique identifier of the Permission.
          example: perm_01HXYZ123456789ABCDEFGHIJ
        slug:
          type: string
          description: A unique key to reference the permission. Must be lowercase and contain only letters, numbers, hyphens, underscores, colons, periods, and asterisks.
          example: documents:read
        name:
          type: string
          description: A descriptive name for the Permission.
          example: View Documents
        description:
          type:
          - string
          - 'null'
          description: An optional description of the Permission.
          example: Allows viewing document contents
        system:
          type: boolean
          description: Whether the permission is a system permission. System permissions are managed by WorkOS and cannot be deleted.
          example: false
        resource_type_slug:
          type: string
          description: The slug of the resource type associated with the permission.
          example: workspace
        created_at:
          format: date-time
          type: string
          description: An ISO 8601 timestamp.
          example: '2026-01-15T12:00:00.000Z'
        updated_at:
          format: date-time
          type: string
          description: An ISO 8601 timestamp.
          example: '2026-01-15T12:00:00.000Z'
      required:
      - object
      - id
      - slug
      - name
      - description
      - system
      - resource_type_slug
      - created_at
      - updated_at
    CreateAuthorizationPermissionDto:
      type: object
      properties:
        slug:
          type: string
          maxLength: 48
          description: A unique key to reference the permission. Must be lowercase and contain only letters, numbers, hyphens, underscores, colons, periods, and asterisks.
          example: documents:read
        name:
          type: string
          maxLength: 48
          description: A descriptive name for the Permission.
          example: View Documents
        description:
          type:
          - string
          - 'null'
          maxLength: 150
          description: An optional description of the Permission.
          example: Allows viewing document contents
        resource_type_slug:
          type: string
          maxLength: 48
          description: The slug of the resource type this permission is scoped to.
          example: document
      required:
      - slug
      - name
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: 'Your WorkOS API key prefixed with `sk_`. Pass it as a Bearer token: `Authorization: Bearer sk_example_123456789`.'
    access_token:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: An SSO access token returned from the Get a Profile and Token endpoint.