WorkOS authorization API

openapi: 3.1.1
info:
  title: WorkOS admin-portal authorization 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: authorization
  description: Authorization and access control.
  x-displayName: Authorization
paths:
  /authorization/organization_memberships/{organization_membership_id}/check:
    post:
      description: Check if an organization membership has a specific permission on a resource. Supports identification by resource_id OR by resource_external_id + resource_type_slug.
      operationId: AuthorizationController_check
      parameters:
      - name: organization_membership_id
        required: true
        in: path
        description: The ID of the organization membership to check.
        schema:
          type: string
          example: om_01HXYZ123456789ABCDEFGHIJ
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckAuthorizationDto'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationCheck'
        '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: Check Authorization
      tags:
      - authorization
      x-mutually-exclusive-body-groups:
        resource_target:
          optional: false
          variants:
            by_id:
            - resource_id
            by_external_id:
            - resource_external_id
            - resource_type_slug
  /authorization/organization_memberships/{organization_membership_id}/resources:
    get:
      description: 'Returns all child resources of a parent resource where the organization membership has a specific permission. This is useful for resource discovery—answering "What projects can this user access in this workspace?"


        You must provide either `parent_resource_id` or both `parent_resource_external_id` and `parent_resource_type_slug` to identify the parent resource.'
      operationId: AuthorizationController_listResourcesForMembership
      parameters:
      - name: organization_membership_id
        required: true
        in: path
        description: The ID of the organization membership.
        schema:
          type: string
          example: om_01HXYZ123456789ABCDEFGHIJ
      - 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'
      - name: permission_slug
        required: true
        in: query
        description: The permission slug to filter by. Only child resources where the organization membership has this permission are returned.
        schema:
          type: string
          example: project:read
      - name: parent_resource_id
        required: false
        in: query
        description: The WorkOS ID of the parent resource. Provide this or both `parent_resource_external_id` and `parent_resource_type_slug`, but not both. Mutually exclusive with `parent_resource_type_slug` and `parent_resource_external_id`.
        schema:
          type: string
          example: authz_resource_01XYZ789
      - name: parent_resource_type_slug
        required: false
        in: query
        description: The slug of the parent resource type. Must be provided together with `parent_resource_external_id`. Required with `parent_resource_external_id`. Mutually exclusive with `parent_resource_id`.
        schema:
          type: string
          example: project
      - name: parent_resource_external_id
        required: false
        in: query
        description: The application-specific external identifier of the parent resource. Must be provided together with `parent_resource_type_slug`. Required with `parent_resource_type_slug`. Mutually exclusive with `parent_resource_id`.
        schema:
          type: string
          example: external_project_123
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationResourceList'
        '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
        '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: List Resources for Organization Membership
      tags:
      - authorization
      x-mutually-exclusive-parameter-groups:
        parent_resource:
          optional: false
          variants:
            by_id:
            - parent_resource_id
            by_external_id:
            - parent_resource_type_slug
            - parent_resource_external_id
  /authorization/organization_memberships/{organization_membership_id}/resources/{resource_id}/permissions:
    get:
      description: Returns all permissions the organization membership effectively has on a resource, including permissions inherited through roles assigned to ancestor resources.
      operationId: AuthorizationController_listEffectivePermissions
      parameters:
      - name: organization_membership_id
        required: true
        in: path
        description: The ID of the organization membership.
        schema:
          type: string
          example: om_01HXYZ123456789ABCDEFGHIJ
      - name: resource_id
        required: true
        in: path
        description: The ID of the authorization resource.
        schema:
          type: string
          example: authz_resource_01HXYZ123456789ABCDEFGHIJ
      - 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'
        '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: List Effective Permissions for an Organization Membership on a Resource
      tags:
      - authorization
  ? /authorization/organization_memberships/{organization_membership_id}/resources/{resource_type_slug}/{external_id}/permissions
  : get:
      description: Returns all permissions the organization membership effectively has on a resource identified by its external ID, including permissions inherited through roles assigned to ancestor resources.
      operationId: AuthorizationController_listEffectivePermissionsByExternalId
      parameters:
      - name: organization_membership_id
        required: true
        in: path
        description: The ID of the organization membership.
        schema:
          type: string
          example: om_01HXYZ123456789ABCDEFGHIJ
      - name: resource_type_slug
        required: true
        in: path
        description: The slug of the resource type.
        schema:
          type: string
          example: document
      - name: external_id
        required: true
        in: path
        description: An identifier you provide to reference the resource in your system.
        schema:
          type: string
          example: doc-456
      - 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'
        '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: List Effective Permissions for an Organization Membership on a Resource by External ID
      tags:
      - authorization
  /authorization/organization_memberships/{organization_membership_id}/role_assignments:
    get:
      description: List all role assignments for an organization membership. This returns all roles that have been assigned to the user on resources, including organization-level and sub-resource roles.
      operationId: AuthorizationRoleAssignmentsController_listRoleAssignments
      parameters:
      - name: organization_membership_id
        required: true
        in: path
        description: The ID of the organization membership.
        schema:
          type: string
          example: om_01HXYZ123456789ABCDEFGHIJ
      - 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'
      - name: resource_id
        required: false
        in: query
        description: Filter assignments by the ID of the resource.
        schema:
          example: authz_resource_01HXYZ123456789ABCDEFGH
          type: string
      - name: resource_external_id
        required: false
        in: query
        description: Filter assignments by the external ID of the resource.
        schema:
          example: project-ext-456
          type: string
      - name: resource_type_slug
        required: false
        in: query
        description: Filter assignments by the slug of the resource type.
        schema:
          example: project
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserRoleAssignmentList'
        '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: List Role Assignments
      tags:
      - authorization
    post:
      description: Assign a role to an organization membership on a specific resource.
      operationId: AuthorizationRoleAssignmentsController_assignRole
      parameters:
      - name: organization_membership_id
        required: true
        in: path
        description: The ID of the organization membership.
        schema:
          type: string
          example: om_01HXYZ123456789ABCDEFGHIJ
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssignRoleDto'
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserRoleAssignment'
              example:
                object: role_assignment
                id: role_assignment_01HXYZ123456789ABCDEFGH
                organization_membership_id: om_01HXYZ123456789ABCDEFGHIJ
                role:
                  slug: editor
                resource:
                  id: authz_resource_01HXYZ123456789ABCDEFGH
                  external_id: project-ext-456
                  resource_type_slug: project
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
          description: Created
        '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: Assign a Role
      tags:
      - authorization
      x-mutually-exclusive-body-groups:
        resource_target:
          optional: false
          variants:
            by_id:
            - resource_id
            by_external_id:
            - resource_external_id
            - resource_type_slug
    delete:
      description: Remove a role assignment by role slug and resource.
      operationId: AuthorizationRoleAssignmentsController_removeRoleByCriteria
      parameters:
      - name: organization_membership_id
        required: true
        in: path
        description: The ID of the organization membership.
        schema:
          type: string
          example: om_01HXYZ123456789ABCDEFGHIJ
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RemoveRoleDto'
      responses:
        '204':
          description: Role assignment removed successfully.
        '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: Remove a Role Assignment
      tags:
      - authorization
      x-mutually-exclusive-body-groups:
        resource_target:
          optional: false
          variants:
            by_id:
            - resource_id
            by_external_id:
            - resource_external_id
            - resource_type_slug
  /authorization/organization_memberships/{organization_membership_id}/role_assignments/{role_assignment_id}:
    delete:
      description: Remove a role assignment using its ID.
      operationId: AuthorizationRoleAssignmentsController_removeRoleById
      parameters:
      - name: organization_membership_id
        required: true
        in: path
        description: The ID of the organization membership.
        schema:
          type: string
          example: om_01HXYZ123456789ABCDEFGHIJ
      - name: role_assignment_id
        required: true
        in: path
        description: The ID of the role assignment to remove.
        schema:
          type: string
          example: role_assignment_01HXYZ123456789ABCDEFGH
      responses:
        '204':
          description: Role assignment removed successfully.
        '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: Remove a Role Assignment by ID
      tags:
      - authorization
  /authorization/organizations/{organizationId}/roles:
    post:
      description: Create a new custom role for this organization.
      operationId: AuthorizationOrganizationRolesController_create
      parameters:
      - name: organizationId
        required: true
        in: path
        description: The ID of the organization.
        schema:
          type: string
          example: org_01EHZNVPK3SFK441A1RGBFSHRT
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrganizationRoleDto'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  slug:
                    type: string
                    description: A unique slug for the role.
                    example: org-billing-admin
                  object:
                    type: string
                    description: Distinguishes the role object.
                    example: role
                    const: role
                  id:
                    type: string
                    description: Unique identifier of the role.
                    example: role_01EHQMYV6MBK39QC5PZXHY59C3
                  name:
                    type: string
                    description: A descriptive name for the role.
                    example: Billing Administrator
                  description:
                    type:
                    - string
                    - 'null'
                    description: An optional description of the role.
                    example: Can manage billing and invoices
                  type:
                    type: string
                    enum:
                    - EnvironmentRole
                    - OrganizationRole
                    description: Whether the role is scoped to the environment or an organization (custom role).
                    example: OrganizationRole
                  resource_type_slug:
                    type: string
                    description: The slug of the resource type the role is scoped to.
                    example: organization
                  permissions:
                    type: array
                    items:
                      type: string
                    description: The permission slugs assigned to the role.
                    example:
                    - posts:read
                    - posts:write
                  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:
                - slug
                - object
                - id
                - name
                - description
                - 

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