diff --git a/.github/workflows/generate-sdks.yml b/.github/workflows/generate-prs.yml similarity index 98% rename from .github/workflows/generate-sdks.yml rename to .github/workflows/generate-prs.yml index 94dc2ef..1a90e18 100644 --- a/.github/workflows/generate-sdks.yml +++ b/.github/workflows/generate-prs.yml @@ -1,4 +1,4 @@ -name: Generate SDKs +name: Generate PRs on: # push: @@ -26,7 +26,7 @@ jobs: id: set-matrix run: echo "matrix=$(jq -c . .github/sdk-matrix.json)" >> "$GITHUB_OUTPUT" - generate: + generate_pr: needs: load-matrix runs-on: ubuntu-latest strategy: @@ -39,7 +39,7 @@ jobs: id: app-token uses: actions/create-github-app-token@fee1f7d63c2ff003460e3d139729b119787bc349 # v2.2.2 with: - app-id: ${{ secrets.SDK_BOT_APP_ID }} + app-id: ${{ vars.SDK_BOT_APP_ID }} private-key: ${{ secrets.SDK_BOT_PRIVATE_KEY }} - name: Checkout openapi-spec diff --git a/.github/workflows/validate-sdks.yml b/.github/workflows/validate-sdks.yml index c5961c1..b5ff082 100644 --- a/.github/workflows/validate-sdks.yml +++ b/.github/workflows/validate-sdks.yml @@ -1,8 +1,9 @@ name: Validate SDKs on: - pull_request: - branches: [main] + # pull_request: + # branches: [main] + workflow_dispatch: concurrency: group: sdk-validation-${{ github.event.pull_request.number }} @@ -42,7 +43,7 @@ jobs: id: app-token uses: actions/create-github-app-token@fee1f7d63c2ff003460e3d139729b119787bc349 # v2.2.2 with: - app-id: ${{ secrets.SDK_BOT_APP_ID }} + app-id: ${{ vars.SDK_BOT_APP_ID }} private-key: ${{ secrets.SDK_BOT_PRIVATE_KEY }} - name: Checkout openapi-spec diff --git a/.last-synced-sha b/.last-synced-sha index 7dd882b..83dc783 100644 --- a/.last-synced-sha +++ b/.last-synced-sha @@ -1 +1 @@ -74967ba74f9d568f8bc971f248db796791cc319f +de458a3b6d5e3e7c8c02eef4117639c81be1a720 diff --git a/spec/open-api-spec.yaml b/spec/open-api-spec.yaml index bd4f57e..a710f24 100644 --- a/spec/open-api-spec.yaml +++ b/spec/open-api-spec.yaml @@ -18,81 +18,7 @@ paths: content: application/json: schema: - type: object - properties: - api_key: - oneOf: - - type: object - properties: - object: - type: string - description: Distinguishes the API Key object. - const: api_key - id: - type: string - description: Unique identifier of the API Key. - example: api_key_01EHZNVPK3SFK441A1RGBFSHRT - owner: - type: object - properties: - type: - type: string - description: The type of the API Key owner. - example: organization - const: organization - id: - type: string - description: Unique identifier of the API Key owner. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - required: - - type - - id - description: The entity that owns the API Key. - name: - type: string - description: A descriptive name for the API Key. - example: Production API Key - obfuscated_value: - type: string - description: An obfuscated representation of the API Key value. - example: sk_...3456 - last_used_at: - type: - - string - - 'null' - description: Timestamp of when the API Key was last used. - example: null - permissions: - type: array - items: - type: string - description: The permission slugs assigned to the API Key. - 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: - - object - - id - - owner - - name - - obfuscated_value - - last_used_at - - permissions - - created_at - - updated_at - - type: 'null' - required: - - api_key + $ref: '#/components/schemas/ApiKeyValidationResponse' '401': description: Unauthorized '422': @@ -110,7 +36,6 @@ paths: - message tags: - api_keys - x-feature-flag: api-keys-management-api /api_keys/{id}: delete: operationId: ApiKeysController_delete @@ -144,7 +69,6 @@ paths: - message tags: - api_keys - x-feature-flag: api-keys-management-api /audit_logs/actions: get: operationId: AuditLogValidatorsController_list @@ -490,14 +414,7 @@ paths: content: application/json: schema: - type: object - properties: - success: - type: boolean - description: Whether the Audit Log event was created successfully. - example: true - required: - - success + $ref: '#/components/schemas/AuditLogEventCreateResponse' example: success: true description: OK @@ -771,60 +688,7 @@ paths: content: application/json: schema: - type: object - properties: - challenge: - type: object - properties: - object: - type: string - description: Distinguishes the authentication challenge object. - const: authentication_challenge - id: - type: string - description: The unique ID of the authentication challenge. - example: auth_challenge_01FVYZ5QM8N98T9ME5BCB2BBMJ - expires_at: - format: date-time - type: string - description: >- - The timestamp when the challenge will expire. Does not - apply to TOTP factors. - example: '2026-01-15T12:00:00.000Z' - code: - type: string - description: The one-time code for the challenge. - example: '123456' - authentication_factor_id: - type: string - description: >- - The unique ID of the authentication factor the - challenge belongs to. - example: auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ - 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 - - authentication_factor_id - - created_at - - updated_at - description: The authentication challenge object. - valid: - type: boolean - description: Whether the code was valid. - example: true - required: - - challenge - - valid + $ref: '#/components/schemas/AuthenticationChallengeVerifyResponse' '400': description: Bad Request content: @@ -920,116 +784,7 @@ paths: content: application/json: schema: - type: object - properties: - object: - type: string - description: Distinguishes the authentication factor object. - const: authentication_factor - id: - type: string - description: The unique ID of the factor. - example: auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ - type: - type: string - enum: - - generic_otp - - sms - - totp - - webauthn - description: The type of the factor to enroll. - example: totp - user_id: - type: string - description: The ID of the [user](/reference/authkit/user). - example: user_01E4ZCR3C56J083X43JQXF3JK5 - sms: - type: object - properties: - phone_number: - type: string - description: The user's phone number for SMS-based authentication. - example: '+15005550006' - required: - - phone_number - description: SMS-based authentication factor details. - totp: - oneOf: - - type: object - properties: - issuer: - type: string - description: >- - Your application or company name displayed in the - user's authenticator app. Defaults to your WorkOS - team name. - example: WorkOS - user: - type: string - description: >- - The user's account name displayed in their - authenticator app. Defaults to the user's email. - example: user@example.com - secret: - type: string - description: >- - TOTP secret that can be manually entered into some - authenticator apps in place of scanning a QR code. - example: JBSWY3DPEHPK3PXP - qr_code: - type: string - description: Base64 encoded image containing scannable QR code. - example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUg... - uri: - type: string - description: >- - The `otpauth` URI that is encoded by the provided - `qr_code`. - example: >- - otpauth://totp/WorkOS:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=WorkOS - required: - - issuer - - user - - secret - - qr_code - - uri - additionalProperties: false - - type: object - properties: - issuer: - type: string - description: >- - Your application or company name displayed in the - user's authenticator app. Defaults to your WorkOS - team name. - example: WorkOS - user: - type: string - description: >- - The user's account name displayed in their - authenticator app. Defaults to the user's email. - example: user@example.com - required: - - issuer - - user - additionalProperties: false - description: TOTP-based authentication factor details. - 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 - - type - - created_at - - updated_at + $ref: '#/components/schemas/AuthenticationFactor' '422': description: Unprocessable Entity content: @@ -1063,116 +818,7 @@ paths: content: application/json: schema: - type: object - properties: - object: - type: string - description: Distinguishes the authentication factor object. - const: authentication_factor - id: - type: string - description: The unique ID of the factor. - example: auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ - type: - type: string - enum: - - generic_otp - - sms - - totp - - webauthn - description: The type of the factor to enroll. - example: totp - user_id: - type: string - description: The ID of the [user](/reference/authkit/user). - example: user_01E4ZCR3C56J083X43JQXF3JK5 - sms: - type: object - properties: - phone_number: - type: string - description: The user's phone number for SMS-based authentication. - example: '+15005550006' - required: - - phone_number - description: SMS-based authentication factor details. - totp: - oneOf: - - type: object - properties: - issuer: - type: string - description: >- - Your application or company name displayed in the - user's authenticator app. Defaults to your WorkOS - team name. - example: WorkOS - user: - type: string - description: >- - The user's account name displayed in their - authenticator app. Defaults to the user's email. - example: user@example.com - secret: - type: string - description: >- - TOTP secret that can be manually entered into some - authenticator apps in place of scanning a QR code. - example: JBSWY3DPEHPK3PXP - qr_code: - type: string - description: Base64 encoded image containing scannable QR code. - example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUg... - uri: - type: string - description: >- - The `otpauth` URI that is encoded by the provided - `qr_code`. - example: >- - otpauth://totp/WorkOS:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=WorkOS - required: - - issuer - - user - - secret - - qr_code - - uri - additionalProperties: false - - type: object - properties: - issuer: - type: string - description: >- - Your application or company name displayed in the - user's authenticator app. Defaults to your WorkOS - team name. - example: WorkOS - user: - type: string - description: >- - The user's account name displayed in their - authenticator app. Defaults to the user's email. - example: user@example.com - required: - - issuer - - user - additionalProperties: false - description: TOTP-based authentication factor details. - 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 - - type - - created_at - - updated_at + $ref: '#/components/schemas/AuthenticationFactor' example: object: authentication_factor id: auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ @@ -1256,49 +902,7 @@ paths: content: application/json: schema: - type: object - properties: - object: - type: string - description: Distinguishes the authentication challenge object. - const: authentication_challenge - id: - type: string - description: The unique ID of the authentication challenge. - example: auth_challenge_01FVYZ5QM8N98T9ME5BCB2BBMJ - expires_at: - format: date-time - type: string - description: >- - The timestamp when the challenge will expire. Does not - apply to TOTP factors. - example: '2026-01-15T12:00:00.000Z' - code: - type: string - description: The one-time code for the challenge. - example: '123456' - authentication_factor_id: - type: string - description: >- - The unique ID of the authentication factor the challenge - belongs to. - example: auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ - 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 - - authentication_factor_id - - created_at - - updated_at + $ref: '#/components/schemas/AuthenticationChallenge' '404': description: Not Found content: @@ -1370,17 +974,7 @@ paths: content: application/json: schema: - type: object - properties: - redirect_uri: - type: string - description: >- - URI to redirect the user back to AuthKit to complete the - OAuth flow. - example: >- - https://your-authkit-domain.workos.com/oauth/authorize/complete?state=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdGF0ZSI6InJhbmRvbV9zdGF0ZV9zdHJpbmciLCJpYXQiOjE3NDI2MDQ4NTN9.abc123def456ghi789 - required: - - redirect_uri + $ref: '#/components/schemas/ExternalAuthCompleteResponse' '400': description: Bad Request content: @@ -1512,16 +1106,7 @@ paths: content: application/json: schema: - type: object - properties: - authorized: - type: boolean - description: >- - Whether the organization membership has the specified - permission on the resource. - example: true - required: - - authorized + $ref: '#/components/schemas/AuthorizationCheck' '403': description: Forbidden content: @@ -1563,7 +1148,6 @@ paths: - message tags: - authorization - x-feature-flag: advanced-rbac-api /authorization/organization_memberships/{organization_membership_id}/resources: get: operationId: AuthorizationController_listResourcesForMembership @@ -1678,122 +1262,18 @@ paths: responses: '200': description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AuthorizationResourceList' + '400': + description: Bad Request content: application/json: schema: type: object properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - type: object - properties: - object: - type: string - description: Distinguishes the Resource object. - const: authorization_resource - name: - type: string - description: A human-readable name for the Resource. - example: Website Redesign - description: - type: - - string - - 'null' - description: An optional description of the Resource. - example: Company website redesign project - organization_id: - type: string - description: The ID of the organization that owns the resource. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - parent_resource_id: - type: - - string - - 'null' - description: >- - The ID of the parent resource, if this resource is - nested. - example: authz_resource_01XYZ789ABCDEFGHIJKLMN - id: - type: string - description: The unique ID of the Resource. - example: authz_resource_01HXYZ123456789ABCDEFGH - external_id: - type: string - description: >- - An identifier you provide to reference the resource - in your system. - example: proj-456 - resource_type_slug: - type: string - description: >- - The slug of the resource type this resource belongs - to. - example: project - 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 - - name - - description - - organization_id - - parent_resource_id - - id - - external_id - - resource_type_slug - - created_at - - updated_at - 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: authz_resource_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: authz_resource_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: >- - Pagination cursors for navigating between pages of - results. - required: - - object - - data - - list_metadata - '400': - description: Bad Request - content: - application/json: - schema: - type: object - properties: - code: + code: type: string description: The error code identifying the type of error. example: bad_request @@ -1846,7 +1326,6 @@ paths: - message tags: - authorization - x-feature-flag: advanced-rbac-api /authorization/organization_memberships/{organization_membership_id}/role_assignments: get: operationId: AuthorizationRoleAssignmentsController_listRoleAssignments @@ -1921,107 +1400,7 @@ paths: content: application/json: schema: - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - type: object - properties: - object: - type: string - description: Distinguishes the role assignment object. - const: role_assignment - id: - type: string - description: Unique identifier of the role assignment. - example: role_assignment_01HXYZ123456789ABCDEFGH - role: - type: object - properties: - slug: - type: string - description: The slug of the assigned role. - example: admin - required: - - slug - description: The role included in the assignment. - resource: - type: object - properties: - id: - type: string - description: The unique ID of the Resource. - example: authz_resource_01HXYZ123456789ABCDEFGH - external_id: - type: string - description: >- - An identifier you provide to reference the - resource in your system. - example: proj-456 - resource_type_slug: - type: string - description: >- - The slug of the resource type this resource - belongs to. - example: project - required: - - id - - external_id - - resource_type_slug - description: The resource to which the role is assigned. - 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 - - role - - resource - - created_at - - updated_at - 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: role_assignment_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: role_assignment_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: >- - Pagination cursors for navigating between pages of - results. - required: - - object - - data - - list_metadata + $ref: '#/components/schemas/RoleAssignmentList' '403': description: Forbidden content: @@ -2050,7 +1429,6 @@ paths: - message tags: - authorization - x-feature-flag: advanced-rbac-api post: operationId: AuthorizationRoleAssignmentsController_assignRole summary: Assign a role @@ -2071,71 +1449,22 @@ paths: $ref: '#/components/schemas/AssignRoleDto' responses: '201': - description: Created content: application/json: schema: - type: object - properties: - object: - type: string - description: Distinguishes the role assignment object. - const: role_assignment - id: - type: string - description: Unique identifier of the role assignment. - example: role_assignment_01HXYZ123456789ABCDEFGH - role: - type: object - properties: - slug: - type: string - description: The slug of the assigned role. - example: admin - required: - - slug - description: The role included in the assignment. - resource: - type: object - properties: - id: - type: string - description: The unique ID of the Resource. - example: authz_resource_01HXYZ123456789ABCDEFGH - external_id: - type: string - description: >- - An identifier you provide to reference the resource in - your system. - example: proj-456 - resource_type_slug: - type: string - description: >- - The slug of the resource type this resource belongs - to. - example: project - required: - - id - - external_id - - resource_type_slug - description: The resource to which the role is assigned. - 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 - - role - - resource - - created_at - - updated_at + $ref: '#/components/schemas/RoleAssignment' + example: + object: role_assignment + id: role_assignment_01HXYZ123456789ABCDEFGH + 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: @@ -2177,7 +1506,6 @@ paths: - message tags: - authorization - x-feature-flag: advanced-rbac-api delete: operationId: AuthorizationRoleAssignmentsController_removeRoleByCriteria summary: Remove a role assignment @@ -2240,7 +1568,6 @@ paths: - message tags: - authorization - x-feature-flag: advanced-rbac-api /authorization/organization_memberships/{organization_membership_id}/role_assignments/{role_assignment_id}: delete: operationId: AuthorizationRoleAssignmentsController_removeRoleById @@ -2292,7 +1619,6 @@ paths: - message tags: - authorization - x-feature-flag: advanced-rbac-api /authorization/organizations/{organizationId}/roles: post: operationId: AuthorizationOrganizationRolesController_create @@ -2323,7 +1649,7 @@ paths: slug: type: string description: A unique slug for the role. - example: org-admin + example: org-billing-admin object: type: string description: Distinguishes the role object. @@ -2336,13 +1662,13 @@ paths: name: type: string description: A descriptive name for the role. - example: Organization Admin + example: Billing Administrator description: type: - string - 'null' description: An optional description of the role. - example: Can manage all resources + example: Can manage billing and invoices type: type: string enum: @@ -2385,6 +1711,7 @@ paths: - permissions - created_at - updated_at + x-inline-with-overrides: true '400': description: Bad Request content: @@ -2464,7 +1791,6 @@ paths: - message tags: - authorization - x-feature-flag: rbac-api get: operationId: AuthorizationOrganizationRolesController_list summary: List organization roles @@ -2566,6 +1892,7 @@ paths: required: - object - data + x-inline-with-overrides: true '403': description: Forbidden content: @@ -2594,7 +1921,6 @@ paths: - message tags: - authorization - x-feature-flag: rbac-api /authorization/organizations/{organizationId}/roles/priority: put: operationId: AuthorizationOrganizationRolesController_updatePriorityOrder @@ -2700,6 +2026,7 @@ paths: required: - object - data + x-inline-with-overrides: true '400': description: Bad Request content: @@ -2776,7 +2103,6 @@ paths: - message tags: - authorization - x-feature-flag: rbac-api /authorization/organizations/{organizationId}/roles/{slug}: get: operationId: AuthorizationOrganizationRolesController_get @@ -2798,7 +2124,7 @@ paths: description: The slug of the role. schema: type: string - example: org-admin + example: org-billing-admin responses: '200': description: OK @@ -2810,7 +2136,7 @@ paths: slug: type: string description: A unique slug for the role. - example: org-admin + example: org-billing-admin object: type: string description: Distinguishes the role object. @@ -2823,13 +2149,13 @@ paths: name: type: string description: A descriptive name for the role. - example: Organization Admin + example: Billing Manager description: type: - string - 'null' description: An optional description of the role. - example: Can manage all resources + example: Can view and export billing reports type: type: string enum: @@ -2872,6 +2198,7 @@ paths: - permissions - created_at - updated_at + x-inline-with-overrides: true '403': description: Forbidden content: @@ -2900,7 +2227,6 @@ paths: - message tags: - authorization - x-feature-flag: rbac-api patch: operationId: AuthorizationOrganizationRolesController_update summary: Update an organization role @@ -2921,7 +2247,7 @@ paths: description: The slug of the role. schema: type: string - example: org-admin + example: org-billing-admin requestBody: required: true content: @@ -2939,7 +2265,7 @@ paths: slug: type: string description: A unique slug for the role. - example: org-admin + example: org-billing-admin object: type: string description: Distinguishes the role object. @@ -2952,13 +2278,13 @@ paths: name: type: string description: A descriptive name for the role. - example: Organization Admin + example: Finance Administrator description: type: - string - 'null' description: An optional description of the role. - example: Can manage all resources + example: Can manage all financial operations type: type: string enum: @@ -3001,6 +2327,7 @@ paths: - permissions - created_at - updated_at + x-inline-with-overrides: true '400': description: Bad Request content: @@ -3061,7 +2388,6 @@ paths: - message tags: - authorization - x-feature-flag: rbac-api delete: operationId: AuthorizationOrganizationRolesController_delete summary: Delete a custom organization role @@ -3165,7 +2491,6 @@ paths: - message tags: - authorization - x-feature-flag: rbac-api /authorization/organizations/{organizationId}/roles/{slug}/permissions: put: operationId: AuthorizationOrganizationRolePermissionsController_setPermissions @@ -3242,8 +2567,10 @@ paths: type: string description: The permission slugs assigned to the role. example: - - posts:read - - posts:write + - billing:read + - billing:write + - invoices:manage + - reports:view created_at: format: date-time type: string @@ -3265,6 +2592,7 @@ paths: - permissions - created_at - updated_at + x-inline-with-overrides: true '403': description: Forbidden content: @@ -3306,7 +2634,6 @@ paths: - message tags: - authorization - x-feature-flag: rbac-api post: operationId: AuthorizationOrganizationRolePermissionsController_addPermission summary: Add a permission to an organization role @@ -3384,8 +2711,7 @@ paths: type: string description: The permission slugs assigned to the role. example: - - posts:read - - posts:write + - reports:export created_at: format: date-time type: string @@ -3407,6 +2733,7 @@ paths: - permissions - created_at - updated_at + x-inline-with-overrides: true '400': description: Bad Request content: @@ -3467,7 +2794,6 @@ paths: - message tags: - authorization - x-feature-flag: rbac-api /authorization/organizations/{organizationId}/roles/{slug}/permissions/{permissionSlug}: delete: operationId: AuthorizationOrganizationRolePermissionsController_removePermission @@ -3501,73 +2827,7 @@ paths: content: application/json: schema: - type: object - properties: - slug: - type: string - description: A unique slug for the role. - example: org-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: Organization Admin - description: - type: - - string - - 'null' - description: An optional description of the role. - example: Can manage all resources - type: - type: string - enum: - - EnvironmentRole - - OrganizationRole - description: >- - Whether the role is scoped to the environment or an - organization. - example: OrganizationRole - resource_type_slug: - type: string - description: The slug of the resource type the role is scoped to. - example: default - 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 - - type - - resource_type_slug - - permissions - - created_at - - updated_at + $ref: '#/components/schemas/Role' '403': description: Forbidden content: @@ -3596,7 +2856,6 @@ paths: - message tags: - authorization - x-feature-flag: rbac-api /authorization/organizations/{organization_id}/resources/{resource_type_slug}/{external_id}: get: operationId: AuthorizationResourcesByExternalIdController_getByExternalId @@ -3627,95 +2886,35 @@ paths: description: An identifier you provide to reference the resource in your system. schema: type: string - example: ext-project-123 + example: proj-456 responses: '200': description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AuthorizationResource' + '403': + description: Forbidden content: application/json: schema: type: object properties: - object: - type: string - description: Distinguishes the Resource object. - const: authorization_resource - name: - type: string - description: A human-readable name for the Resource. - example: Website Redesign - description: - type: - - string - - 'null' - description: An optional description of the Resource. - example: Company website redesign project - organization_id: + message: type: string - description: The ID of the organization that owns the resource. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - parent_resource_id: - type: - - string - - 'null' - description: The ID of the parent resource, if this resource is nested. - example: authz_resource_01XYZ789ABCDEFGHIJKLMN - id: - type: string - description: The unique ID of the Resource. - example: authz_resource_01HXYZ123456789ABCDEFGH - external_id: - type: string - description: >- - An identifier you provide to reference the resource in - your system. - example: proj-456 - resource_type_slug: - type: string - description: The slug of the resource type this resource belongs to. - example: project - 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 - - name - - description - - organization_id - - parent_resource_id - - id - - external_id - - resource_type_slug - - created_at - - updated_at - '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: + 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''.' @@ -3723,7 +2922,6 @@ paths: - message tags: - authorization - x-feature-flag: advanced-rbac-api patch: operationId: AuthorizationResourcesByExternalIdController_updateByExternalId summary: Update a resource by external ID @@ -3749,7 +2947,7 @@ paths: description: An identifier you provide to reference the resource in your system. schema: type: string - example: ext-project-123 + example: proj-456 requestBody: required: true content: @@ -3771,13 +2969,13 @@ paths: name: type: string description: A human-readable name for the Resource. - example: Website Redesign + example: Updated Name description: type: - string - 'null' description: An optional description of the Resource. - example: Company website redesign project + example: Updated description organization_id: type: string description: The ID of the organization that owns the resource. @@ -3787,7 +2985,7 @@ paths: - string - 'null' description: The ID of the parent resource, if this resource is nested. - example: authz_resource_01XYZ789ABCDEFGHIJKLMN + example: authz_resource_01HXYZ123456789ABCDEFGHIJ id: type: string description: The unique ID of the Resource. @@ -3823,6 +3021,26 @@ paths: - 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: lock_timeout + const: lock_timeout + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message '403': description: Forbidden content: @@ -3849,6 +3067,25 @@ paths: 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: resource_type_update_in_progress + const: resource_type_update_in_progress + 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: @@ -3864,7 +3101,6 @@ paths: - message tags: - authorization - x-feature-flag: advanced-rbac-api delete: operationId: AuthorizationResourcesByExternalIdController_deleteByExternalId summary: Delete an authorization resource by external ID @@ -3892,7 +3128,7 @@ paths: description: An identifier you provide to reference the resource in your system. schema: type: string - example: ext-project-123 + example: proj-456 - name: cascade_delete required: false in: query @@ -3907,21 +3143,27 @@ paths: responses: '204': description: No Content - '403': - description: Forbidden + '400': + description: Bad Request content: application/json: schema: type: object properties: + code: + type: string + description: The error code identifying the type of error. + example: lock_timeout + const: lock_timeout message: type: string description: A human-readable description of the error. - example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + example: Request could not be processed. required: + - code - message - '404': - description: Not Found + '403': + description: Forbidden content: application/json: schema: @@ -3933,28 +3175,55 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - '409': - description: '' + '404': + description: Not Found content: application/json: schema: type: object properties: - code: - type: string - description: The error code identifying the type of error. - example: resource_has_dependents - const: resource_has_dependents message: type: string description: A human-readable description of the error. - example: Request could not be processed. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - - code - message + '409': + description: '' + content: + application/json: + schema: + oneOf: + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: resource_has_dependents + const: resource_has_dependents + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: resource_type_update_in_progress + const: resource_type_update_in_progress + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message tags: - authorization - x-feature-flag: advanced-rbac-api /authorization/organizations/{organization_id}/resources/{resource_type_slug}/{external_id}/organization_memberships: get: operationId: >- @@ -4066,121 +3335,8 @@ paths: content: application/json: schema: - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - type: object - properties: - object: - type: string - description: Distinguishes the organization membership object. - const: organization_membership - id: - type: string - description: The unique ID of the organization membership. - example: om_01HXYZ123456789ABCDEFGHIJ - user_id: - type: string - description: The ID of the user. - example: user_01EHQTV6MWP9P1F4ZXGXMC8ABB - organization_id: - type: string - description: >- - The ID of the organization which the user belongs - to. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - status: - type: string - enum: - - active - - inactive - - pending - description: >- - The status of the organization membership. One of - `active`, `inactive`, or `pending`. - example: active - directory_managed: - type: boolean - description: >- - Whether this organization membership is managed by a - directory sync connection. - example: false - organization_name: - type: string - description: >- - The name of the organization which the user belongs - to. - example: Acme Corp - custom_attributes: - type: object - additionalProperties: {} - description: >- - An object containing IdP-sourced attributes from the - linked [Directory - User](/reference/directory-sync/directory-user) or - [SSO Profile](/reference/sso/profile). Directory - User attributes take precedence when both are - linked. - example: - department: Engineering - title: Developer Experience Engineer - location: Brooklyn - 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 - - user_id - - organization_id - - status - - directory_managed - - created_at - - updated_at - 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: om_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: om_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: >- - Pagination cursors for navigating between pages of - results. - required: - - object - - data - - list_metadata + $ref: >- + #/components/schemas/UserlandUserOrganizationMembershipBaseList '400': description: Bad Request content: @@ -4241,7 +3397,6 @@ paths: - message tags: - authorization - x-feature-flag: advanced-rbac-api /authorization/permissions: get: operationId: AuthorizationPermissionsController_list @@ -4303,142 +3458,41 @@ paths: responses: '200': description: OK - content: - application/json: - schema: - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - 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 - 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 - '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 - tags: - - permissions - x-feature-flag: rbac-api - post: - operationId: AuthorizationPermissionsController_create - summary: Create a permission - description: >- - Create a new permission in your WorkOS environment. The permission can - then be assigned to environment roles and organization roles. - parameters: [] - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreateAuthorizationPermissionDto' - responses: - '201': - description: Created + 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 + tags: + - permissions + post: + operationId: AuthorizationPermissionsController_create + summary: Create a permission + description: >- + Create a new permission in your WorkOS environment. The permission can + then be assigned to environment roles and organization roles. + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateAuthorizationPermissionDto' + responses: + '201': + description: Created content: application/json: schema: @@ -4480,7 +3534,7 @@ paths: description: >- The slug of the resource type associated with the permission. - example: workspace + example: document created_at: format: date-time type: string @@ -4501,6 +3555,7 @@ paths: - resource_type_slug - created_at - updated_at + x-inline-with-overrides: true '400': description: Bad Request content: @@ -4567,7 +3622,6 @@ paths: - message tags: - permissions - x-feature-flag: rbac-api /authorization/permissions/{slug}: get: operationId: AuthorizationPermissionsController_find @@ -4590,65 +3644,7 @@ paths: 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: 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 + $ref: '#/components/schemas/AuthorizationPermission' '404': description: Not Found content: @@ -4664,7 +3660,6 @@ paths: - message tags: - permissions - x-feature-flag: rbac-api patch: operationId: AuthorizationPermissionsController_update summary: Update a permission @@ -4694,65 +3689,7 @@ paths: 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: 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 + $ref: '#/components/schemas/AuthorizationPermission' '403': description: Forbidden content: @@ -4794,7 +3731,6 @@ paths: - message tags: - permissions - x-feature-flag: rbac-api delete: operationId: AuthorizationPermissionsController_delete summary: Delete a permission @@ -4841,7 +3777,6 @@ paths: - message tags: - permissions - x-feature-flag: rbac-api /authorization/resources: get: operationId: AuthorizationResourcesController_list @@ -4945,157 +3880,52 @@ paths: responses: '200': description: OK - content: - application/json: - schema: - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - type: object - properties: - object: - type: string - description: Distinguishes the Resource object. - const: authorization_resource - name: - type: string - description: A human-readable name for the Resource. - example: Website Redesign - description: - type: - - string - - 'null' - description: An optional description of the Resource. - example: Company website redesign project - organization_id: - type: string - description: The ID of the organization that owns the resource. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - parent_resource_id: - type: - - string - - 'null' - description: >- - The ID of the parent resource, if this resource is - nested. - example: authz_resource_01XYZ789ABCDEFGHIJKLMN - id: - type: string - description: The unique ID of the Resource. - example: authz_resource_01HXYZ123456789ABCDEFGH - external_id: - type: string - description: >- - An identifier you provide to reference the resource - in your system. - example: proj-456 - resource_type_slug: - type: string - description: >- - The slug of the resource type this resource belongs - to. - example: project - 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 - - name - - description - - organization_id - - parent_resource_id - - id - - external_id - - resource_type_slug - - created_at - - updated_at - 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: authz_resource_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: authz_resource_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: >- - Pagination cursors for navigating between pages of - results. - required: - - object - - data - - list_metadata - '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 - '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 - tags: - - authorization - x-feature-flag: advanced-rbac-api - post: - operationId: AuthorizationResourcesController_create - summary: Create an authorization resource - description: Create a new authorization resource. - parameters: [] - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreateAuthorizationResourceDto' - responses: - '201': - description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/AuthorizationResourceList' + '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 + '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 + tags: + - authorization + post: + operationId: AuthorizationResourcesController_create + summary: Create an authorization resource + description: Create a new authorization resource. + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateAuthorizationResourceDto' + responses: + '201': + description: Created content: application/json: schema: @@ -5108,23 +3938,23 @@ paths: name: type: string description: A human-readable name for the Resource. - example: Website Redesign + example: Acme Workspace description: type: - string - 'null' description: An optional description of the Resource. - example: Company website redesign project + example: Primary workspace for the Acme team organization_id: type: string description: The ID of the organization that owns the resource. - example: org_01EHZNVPK3SFK441A1RGBFSHRT + example: org_01EHQMYV6MBK39QC5PZXHY59C3 parent_resource_id: type: - string - 'null' description: The ID of the parent resource, if this resource is nested. - example: authz_resource_01XYZ789ABCDEFGHIJKLMN + example: authz_resource_01HXYZ123456789ABCDEFGHIJ id: type: string description: The unique ID of the Resource. @@ -5134,11 +3964,11 @@ paths: description: >- An identifier you provide to reference the resource in your system. - example: proj-456 + example: my-workspace-01 resource_type_slug: type: string description: The slug of the resource type this resource belongs to. - example: project + example: workspace created_at: format: date-time type: string @@ -5160,25 +3990,41 @@ paths: - 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 + oneOf: + - 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 + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: lock_timeout + const: lock_timeout + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message '403': description: Forbidden content: @@ -5210,20 +4056,35 @@ paths: content: application/json: schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: authorization_resource_external_id_conflict - const: authorization_resource_external_id_conflict - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message + oneOf: + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: authorization_resource_external_id_conflict + const: authorization_resource_external_id_conflict + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: resource_type_update_in_progress + const: resource_type_update_in_progress + 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: @@ -5239,7 +4100,6 @@ paths: - message tags: - authorization - x-feature-flag: advanced-rbac-api /authorization/resources/{resource_id}: get: operationId: AuthorizationResourcesController_findById @@ -5259,67 +4119,7 @@ paths: content: application/json: schema: - type: object - properties: - object: - type: string - description: Distinguishes the Resource object. - const: authorization_resource - name: - type: string - description: A human-readable name for the Resource. - example: Website Redesign - description: - type: - - string - - 'null' - description: An optional description of the Resource. - example: Company website redesign project - organization_id: - type: string - description: The ID of the organization that owns the resource. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - parent_resource_id: - type: - - string - - 'null' - description: The ID of the parent resource, if this resource is nested. - example: authz_resource_01XYZ789ABCDEFGHIJKLMN - id: - type: string - description: The unique ID of the Resource. - example: authz_resource_01HXYZ123456789ABCDEFGH - external_id: - type: string - description: >- - An identifier you provide to reference the resource in - your system. - example: proj-456 - resource_type_slug: - type: string - description: The slug of the resource type this resource belongs to. - example: project - 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 - - name - - description - - organization_id - - parent_resource_id - - id - - external_id - - resource_type_slug - - created_at - - updated_at + $ref: '#/components/schemas/AuthorizationResource' '403': description: Forbidden content: @@ -5361,7 +4161,6 @@ paths: - message tags: - authorization - x-feature-flag: advanced-rbac-api patch: operationId: AuthorizationResourcesController_update summary: Update a resource @@ -5395,13 +4194,13 @@ paths: name: type: string description: A human-readable name for the Resource. - example: Website Redesign + example: Updated Name description: type: - string - 'null' description: An optional description of the Resource. - example: Company website redesign project + example: Updated description organization_id: type: string description: The ID of the organization that owns the resource. @@ -5411,7 +4210,7 @@ paths: - string - 'null' description: The ID of the parent resource, if this resource is nested. - example: authz_resource_01XYZ789ABCDEFGHIJKLMN + example: authz_resource_01HXYZ123456789ABCDEFGHIJ id: type: string description: The unique ID of the Resource. @@ -5447,17 +4246,37 @@ paths: - resource_type_slug - created_at - updated_at - '403': - description: Forbidden + 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: lock_timeout + const: lock_timeout message: type: string description: A human-readable description of the error. - example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + 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': @@ -5473,6 +4292,25 @@ paths: 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: resource_type_update_in_progress + const: resource_type_update_in_progress + 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: @@ -5488,7 +4326,6 @@ paths: - message tags: - authorization - x-feature-flag: advanced-rbac-api delete: operationId: AuthorizationResourcesController_delete summary: Delete an authorization resource @@ -5515,21 +4352,27 @@ paths: responses: '204': description: No Content - '403': - description: Forbidden + '400': + description: Bad Request content: application/json: schema: type: object properties: + code: + type: string + description: The error code identifying the type of error. + example: lock_timeout + const: lock_timeout message: type: string description: A human-readable description of the error. - example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + example: Request could not be processed. required: + - code - message - '404': - description: Not Found + '403': + description: Forbidden content: application/json: schema: @@ -5541,28 +4384,55 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - '409': - description: '' + '404': + description: Not Found content: application/json: schema: type: object properties: - code: - type: string - description: The error code identifying the type of error. - example: resource_has_dependents - const: resource_has_dependents message: type: string description: A human-readable description of the error. - example: Request could not be processed. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - - code - message + '409': + description: '' + content: + application/json: + schema: + oneOf: + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: resource_has_dependents + const: resource_has_dependents + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: resource_type_update_in_progress + const: resource_type_update_in_progress + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message tags: - authorization - x-feature-flag: advanced-rbac-api /authorization/resources/{resource_id}/organization_memberships: get: operationId: AuthorizationResourcesController_listOrganizationMembershipsForResource @@ -5658,121 +4528,8 @@ paths: content: application/json: schema: - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - type: object - properties: - object: - type: string - description: Distinguishes the organization membership object. - const: organization_membership - id: - type: string - description: The unique ID of the organization membership. - example: om_01HXYZ123456789ABCDEFGHIJ - user_id: - type: string - description: The ID of the user. - example: user_01EHQTV6MWP9P1F4ZXGXMC8ABB - organization_id: - type: string - description: >- - The ID of the organization which the user belongs - to. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - status: - type: string - enum: - - active - - inactive - - pending - description: >- - The status of the organization membership. One of - `active`, `inactive`, or `pending`. - example: active - directory_managed: - type: boolean - description: >- - Whether this organization membership is managed by a - directory sync connection. - example: false - organization_name: - type: string - description: >- - The name of the organization which the user belongs - to. - example: Acme Corp - custom_attributes: - type: object - additionalProperties: {} - description: >- - An object containing IdP-sourced attributes from the - linked [Directory - User](/reference/directory-sync/directory-user) or - [SSO Profile](/reference/sso/profile). Directory - User attributes take precedence when both are - linked. - example: - department: Engineering - title: Developer Experience Engineer - location: Brooklyn - 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 - - user_id - - organization_id - - status - - directory_managed - - created_at - - updated_at - 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: om_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: om_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: >- - Pagination cursors for navigating between pages of - results. - required: - - object - - data - - list_metadata + $ref: >- + #/components/schemas/UserlandUserOrganizationMembershipBaseList '400': description: Bad Request content: @@ -5833,7 +4590,6 @@ paths: - message tags: - authorization - x-feature-flag: advanced-rbac-api /authorization/roles: post: operationId: AuthorizationRolesController_create @@ -5857,7 +4613,7 @@ paths: slug: type: string description: A unique slug for the role. - example: admin + example: editor object: type: string description: Distinguishes the role object. @@ -5870,13 +4626,13 @@ paths: name: type: string description: A descriptive name for the role. - example: Admin + example: Editor description: type: - string - 'null' description: An optional description of the role. - example: Can manage all resources + example: Can edit resources type: type: string enum: @@ -5919,6 +4675,7 @@ paths: - permissions - created_at - updated_at + x-inline-with-overrides: true '400': description: Bad Request content: @@ -5998,7 +4755,6 @@ paths: - message tags: - authorization - x-feature-flag: rbac-api get: operationId: AuthorizationRolesController_list summary: List environment roles @@ -6010,86 +4766,7 @@ paths: content: application/json: schema: - type: object - properties: - object: - type: string - example: list - const: list - data: - type: array - items: - type: object - properties: - slug: - type: string - description: A unique slug for the role. - example: 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: Admin - description: - type: - - string - - 'null' - description: An optional description of the role. - example: Can manage all resources - type: - type: string - enum: - - EnvironmentRole - - OrganizationRole - description: >- - Whether the role is scoped to the environment or an - organization. - example: EnvironmentRole - resource_type_slug: - type: string - description: The slug of the resource type the role is scoped to. - example: default - 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 - - type - - resource_type_slug - - permissions - - created_at - - updated_at - description: The list of records for the current page. - required: - - object - - data + $ref: '#/components/schemas/RoleList' '403': description: Forbidden content: @@ -6105,7 +4782,6 @@ paths: - message tags: - authorization - x-feature-flag: rbac-api /authorization/roles/{slug}: get: operationId: AuthorizationRolesController_get @@ -6122,97 +4798,31 @@ paths: responses: '200': description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Role' + '403': + description: Forbidden content: application/json: schema: type: object properties: - slug: - type: string - description: A unique slug for the role. - example: admin - object: + message: 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: Admin - description: - type: - - string - - 'null' - description: An optional description of the role. - example: Can manage all resources - type: - type: string - enum: - - EnvironmentRole - - OrganizationRole - description: >- - Whether the role is scoped to the environment or an - organization. - example: EnvironmentRole - resource_type_slug: - type: string - description: The slug of the resource type the role is scoped to. - example: default - 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 - - type - - resource_type_slug - - permissions - - created_at - - updated_at - '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: + 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''.' @@ -6220,7 +4830,6 @@ paths: - message tags: - authorization - x-feature-flag: rbac-api patch: operationId: AuthorizationRolesController_update summary: Update an environment role @@ -6263,13 +4872,13 @@ paths: name: type: string description: A descriptive name for the role. - example: Admin + example: Super Administrator description: type: - string - 'null' description: An optional description of the role. - example: Can manage all resources + example: Full administrative access to all resources type: type: string enum: @@ -6312,6 +4921,7 @@ paths: - permissions - created_at - updated_at + x-inline-with-overrides: true '400': description: Bad Request content: @@ -6372,7 +4982,6 @@ paths: - message tags: - authorization - x-feature-flag: rbac-api /authorization/roles/{slug}/permissions: put: operationId: AuthorizationRolePermissionsController_setPermissions @@ -6442,8 +5051,10 @@ paths: type: string description: The permission slugs assigned to the role. example: - - posts:read - - posts:write + - billing:read + - billing:write + - invoices:manage + - reports:view created_at: format: date-time type: string @@ -6465,6 +5076,7 @@ paths: - permissions - created_at - updated_at + x-inline-with-overrides: true '400': description: Bad Request content: @@ -6525,7 +5137,6 @@ paths: - message tags: - authorization - x-feature-flag: rbac-api post: operationId: AuthorizationRolePermissionsController_addPermission summary: Add a permission to an environment role @@ -6596,8 +5207,7 @@ paths: type: string description: The permission slugs assigned to the role. example: - - posts:read - - posts:write + - reports:export created_at: format: date-time type: string @@ -6619,6 +5229,7 @@ paths: - permissions - created_at - updated_at + x-inline-with-overrides: true '400': description: Bad Request content: @@ -6679,7 +5290,6 @@ paths: - message tags: - authorization - x-feature-flag: rbac-api /connect/applications: get: operationId: ApplicationsController_list @@ -6753,215 +5363,7 @@ paths: content: application/json: schema: - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - allOf: - - type: object - properties: - object: - type: string - description: Distinguishes the connect application object. - example: connect_application - const: connect_application - id: - type: string - description: The unique ID of the connect application. - example: conn_app_01HXYZ123456789ABCDEFGHIJ - client_id: - type: string - description: The client ID of the connect application. - example: client_01HXYZ123456789ABCDEFGHIJ - description: - type: - - string - - 'null' - description: A description of the connect application. - example: >- - A sample application for managing user - connections. - name: - type: string - description: The name of the connect application. - example: My Application - scopes: - type: array - items: - type: string - description: The scopes available for this application. - example: - - openid - - profile - - email - 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 - - client_id - - description - - name - - scopes - - created_at - - updated_at - - oneOf: - - allOf: - - type: object - properties: - application_type: - type: string - description: The type of the application. - const: oauth - redirect_uris: - type: array - items: - type: object - properties: - uri: - type: string - format: uri - description: The redirect URI for the application. - example: https://example.com/callback - default: - type: boolean - description: >- - Whether this is the default redirect - URI. - example: true - required: - - uri - - default - description: >- - The redirect URIs configured for this - application. - uses_pkce: - type: boolean - description: >- - Whether the application uses PKCE for - authorization. - example: true - required: - - application_type - - redirect_uris - - uses_pkce - - oneOf: - - type: object - properties: - is_first_party: - type: boolean - description: >- - Whether the application is a first-party - application. - example: true - const: true - required: - - is_first_party - - type: object - properties: - is_first_party: - type: boolean - description: >- - Whether the application is a first-party - application. - example: false - const: false - was_dynamically_registered: - type: boolean - description: >- - Whether the application was dynamically - registered. - example: false - const: false - organization_id: - type: string - description: >- - The ID of the organization the - application belongs to. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - required: - - is_first_party - - was_dynamically_registered - - organization_id - - type: object - properties: - is_first_party: - type: boolean - description: >- - Whether the application is a first-party - application. - example: false - const: false - was_dynamically_registered: - type: boolean - description: >- - Whether the application was dynamically - registered. - example: true - const: true - required: - - is_first_party - - was_dynamically_registered - - type: object - properties: - application_type: - type: string - description: The type of the application. - example: m2m - const: m2m - organization_id: - type: string - description: >- - The ID of the organization the application - belongs to. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - required: - - application_type - - organization_id - 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: conn_app_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: conn_app_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: >- - Pagination cursors for navigating between pages of - results. - required: - - object - - data - - list_metadata + $ref: '#/components/schemas/ConnectApplicationList' '422': description: Unprocessable Entity content: @@ -6977,7 +5379,6 @@ paths: - message tags: - applications - x-feature-flag: connect-management-api post: operationId: ApplicationsController_create summary: Create a Connect Application @@ -6999,173 +5400,7 @@ paths: content: application/json: schema: - allOf: - - type: object - properties: - object: - type: string - description: Distinguishes the connect application object. - example: connect_application - const: connect_application - id: - type: string - description: The unique ID of the connect application. - example: conn_app_01HXYZ123456789ABCDEFGHIJ - client_id: - type: string - description: The client ID of the connect application. - example: client_01HXYZ123456789ABCDEFGHIJ - description: - type: - - string - - 'null' - description: A description of the connect application. - example: A sample application for managing user connections. - name: - type: string - description: The name of the connect application. - example: My Application - scopes: - type: array - items: - type: string - description: The scopes available for this application. - example: - - openid - - profile - - email - 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 - - client_id - - description - - name - - scopes - - created_at - - updated_at - - oneOf: - - allOf: - - type: object - properties: - application_type: - type: string - description: The type of the application. - const: oauth - redirect_uris: - type: array - items: - type: object - properties: - uri: - type: string - format: uri - description: The redirect URI for the application. - example: https://example.com/callback - default: - type: boolean - description: >- - Whether this is the default redirect - URI. - example: true - required: - - uri - - default - description: >- - The redirect URIs configured for this - application. - uses_pkce: - type: boolean - description: >- - Whether the application uses PKCE for - authorization. - example: true - required: - - application_type - - redirect_uris - - uses_pkce - - oneOf: - - type: object - properties: - is_first_party: - type: boolean - description: >- - Whether the application is a first-party - application. - example: true - const: true - required: - - is_first_party - - type: object - properties: - is_first_party: - type: boolean - description: >- - Whether the application is a first-party - application. - example: false - const: false - was_dynamically_registered: - type: boolean - description: >- - Whether the application was dynamically - registered. - example: false - const: false - organization_id: - type: string - description: >- - The ID of the organization the application - belongs to. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - required: - - is_first_party - - was_dynamically_registered - - organization_id - - type: object - properties: - is_first_party: - type: boolean - description: >- - Whether the application is a first-party - application. - example: false - const: false - was_dynamically_registered: - type: boolean - description: >- - Whether the application was dynamically - registered. - example: true - const: true - required: - - is_first_party - - was_dynamically_registered - - type: object - properties: - application_type: - type: string - description: The type of the application. - example: m2m - const: m2m - organization_id: - type: string - description: >- - The ID of the organization the application belongs - to. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - required: - - application_type - - organization_id + $ref: '#/components/schemas/ConnectApplication' '404': description: Not Found content: @@ -7194,7 +5429,6 @@ paths: - message tags: - applications - x-feature-flag: connect-management-api /connect/applications/{id}: get: operationId: ApplicationsController_find @@ -7214,173 +5448,7 @@ paths: content: application/json: schema: - allOf: - - type: object - properties: - object: - type: string - description: Distinguishes the connect application object. - example: connect_application - const: connect_application - id: - type: string - description: The unique ID of the connect application. - example: conn_app_01HXYZ123456789ABCDEFGHIJ - client_id: - type: string - description: The client ID of the connect application. - example: client_01HXYZ123456789ABCDEFGHIJ - description: - type: - - string - - 'null' - description: A description of the connect application. - example: A sample application for managing user connections. - name: - type: string - description: The name of the connect application. - example: My Application - scopes: - type: array - items: - type: string - description: The scopes available for this application. - example: - - openid - - profile - - email - 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 - - client_id - - description - - name - - scopes - - created_at - - updated_at - - oneOf: - - allOf: - - type: object - properties: - application_type: - type: string - description: The type of the application. - const: oauth - redirect_uris: - type: array - items: - type: object - properties: - uri: - type: string - format: uri - description: The redirect URI for the application. - example: https://example.com/callback - default: - type: boolean - description: >- - Whether this is the default redirect - URI. - example: true - required: - - uri - - default - description: >- - The redirect URIs configured for this - application. - uses_pkce: - type: boolean - description: >- - Whether the application uses PKCE for - authorization. - example: true - required: - - application_type - - redirect_uris - - uses_pkce - - oneOf: - - type: object - properties: - is_first_party: - type: boolean - description: >- - Whether the application is a first-party - application. - example: true - const: true - required: - - is_first_party - - type: object - properties: - is_first_party: - type: boolean - description: >- - Whether the application is a first-party - application. - example: false - const: false - was_dynamically_registered: - type: boolean - description: >- - Whether the application was dynamically - registered. - example: false - const: false - organization_id: - type: string - description: >- - The ID of the organization the application - belongs to. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - required: - - is_first_party - - was_dynamically_registered - - organization_id - - type: object - properties: - is_first_party: - type: boolean - description: >- - Whether the application is a first-party - application. - example: false - const: false - was_dynamically_registered: - type: boolean - description: >- - Whether the application was dynamically - registered. - example: true - const: true - required: - - is_first_party - - was_dynamically_registered - - type: object - properties: - application_type: - type: string - description: The type of the application. - example: m2m - const: m2m - organization_id: - type: string - description: >- - The ID of the organization the application belongs - to. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - required: - - application_type - - organization_id + $ref: '#/components/schemas/ConnectApplication' '404': description: Not Found content: @@ -7396,7 +5464,6 @@ paths: - message tags: - applications - x-feature-flag: connect-management-api put: operationId: ApplicationsController_update summary: Update a Connect Application @@ -7424,173 +5491,7 @@ paths: content: application/json: schema: - allOf: - - type: object - properties: - object: - type: string - description: Distinguishes the connect application object. - example: connect_application - const: connect_application - id: - type: string - description: The unique ID of the connect application. - example: conn_app_01HXYZ123456789ABCDEFGHIJ - client_id: - type: string - description: The client ID of the connect application. - example: client_01HXYZ123456789ABCDEFGHIJ - description: - type: - - string - - 'null' - description: A description of the connect application. - example: A sample application for managing user connections. - name: - type: string - description: The name of the connect application. - example: My Application - scopes: - type: array - items: - type: string - description: The scopes available for this application. - example: - - openid - - profile - - email - 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 - - client_id - - description - - name - - scopes - - created_at - - updated_at - - oneOf: - - allOf: - - type: object - properties: - application_type: - type: string - description: The type of the application. - const: oauth - redirect_uris: - type: array - items: - type: object - properties: - uri: - type: string - format: uri - description: The redirect URI for the application. - example: https://example.com/callback - default: - type: boolean - description: >- - Whether this is the default redirect - URI. - example: true - required: - - uri - - default - description: >- - The redirect URIs configured for this - application. - uses_pkce: - type: boolean - description: >- - Whether the application uses PKCE for - authorization. - example: true - required: - - application_type - - redirect_uris - - uses_pkce - - oneOf: - - type: object - properties: - is_first_party: - type: boolean - description: >- - Whether the application is a first-party - application. - example: true - const: true - required: - - is_first_party - - type: object - properties: - is_first_party: - type: boolean - description: >- - Whether the application is a first-party - application. - example: false - const: false - was_dynamically_registered: - type: boolean - description: >- - Whether the application was dynamically - registered. - example: false - const: false - organization_id: - type: string - description: >- - The ID of the organization the application - belongs to. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - required: - - is_first_party - - was_dynamically_registered - - organization_id - - type: object - properties: - is_first_party: - type: boolean - description: >- - Whether the application is a first-party - application. - example: false - const: false - was_dynamically_registered: - type: boolean - description: >- - Whether the application was dynamically - registered. - example: true - const: true - required: - - is_first_party - - was_dynamically_registered - - type: object - properties: - application_type: - type: string - description: The type of the application. - example: m2m - const: m2m - organization_id: - type: string - description: >- - The ID of the organization the application belongs - to. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - required: - - application_type - - organization_id + $ref: '#/components/schemas/ConnectApplication' '404': description: Not Found content: @@ -7619,7 +5520,6 @@ paths: - message tags: - applications - x-feature-flag: connect-management-api delete: operationId: ApplicationsController_delete summary: Delete a Connect Application @@ -7650,7 +5550,6 @@ paths: - message tags: - applications - x-feature-flag: connect-management-api /connect/applications/{id}/client_secrets: get: operationId: ApplicationCredentialsController_list @@ -7728,7 +5627,6 @@ paths: - message tags: - application.client-secrets - x-feature-flag: connect-management-api post: operationId: ApplicationCredentialsController_create summary: Create a new client secret for a Connect Application @@ -7753,54 +5651,7 @@ paths: content: application/json: schema: - type: object - properties: - object: - type: string - description: Distinguishes the connect application secret object. - const: connect_application_secret - id: - type: string - description: The unique ID of the client secret. - example: secret_01J9Q2Z3X4Y5W6V7U8T9S0R1Q - secret_hint: - type: string - description: >- - A hint showing the last few characters of the secret - value. - example: abc123 - last_used_at: - type: - - string - - 'null' - description: >- - The timestamp when the client secret was last used, or - null if never used. - example: null - 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' - secret: - type: string - description: >- - The plaintext secret value. Only returned at creation time - and cannot be retrieved later. - example: abc123def456ghi789jkl012mno345pqr678stu901vwx234yz - required: - - object - - id - - secret_hint - - last_used_at - - created_at - - updated_at - - secret + $ref: '#/components/schemas/NewConnectApplicationSecret' '404': description: Not Found content: @@ -7829,7 +5680,6 @@ paths: - message tags: - application.client-secrets - x-feature-flag: connect-management-api /connect/client_secrets/{id}: delete: operationId: ApplicationCredentialsController_delete @@ -7861,7 +5711,6 @@ paths: - message tags: - application.client-secrets - x-feature-flag: connect-management-api /connections: get: operationId: ConnectionsController_list @@ -7995,205 +5844,7 @@ paths: content: application/json: schema: - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - type: object - properties: - object: - type: string - description: Distinguishes the Connection object. - const: connection - id: - type: string - description: Unique identifier for the Connection. - example: conn_01E4ZCR3C56J083X43JQXF3JK5 - organization_id: - type: string - description: >- - Unique identifier for the Organization in which the - Connection resides. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - connection_type: - type: string - enum: - - Pending - - ADFSSAML - - AdpOidc - - AppleOAuth - - Auth0Migration - - Auth0SAML - - AzureSAML - - BitbucketOAuth - - CasSAML - - ClassLinkSAML - - CleverOIDC - - CloudflareSAML - - CyberArkSAML - - DiscordOAuth - - DuoSAML - - EntraIdOIDC - - GenericOIDC - - GenericSAML - - GitHubOAuth - - GitLabOAuth - - GoogleOAuth - - GoogleOIDC - - GoogleSAML - - IntuitOAuth - - JumpCloudSAML - - KeycloakSAML - - LastPassSAML - - LinkedInOAuth - - LoginGovOidc - - MagicLink - - MicrosoftOAuth - - MiniOrangeSAML - - NetIqSAML - - OktaOIDC - - OktaSAML - - OneLoginSAML - - OracleSAML - - PingFederateSAML - - PingOneSAML - - RipplingSAML - - SalesforceSAML - - ShibbolethGenericSAML - - ShibbolethSAML - - SimpleSamlPhpSAML - - SalesforceOAuth - - SlackOAuth - - TestIdp - - VercelMarketplaceOAuth - - VercelOAuth - - VMwareSAML - - XeroOAuth - description: >- - The type of the SSO Connection used to authenticate - the user. The Connection type may be used to - dynamically generate authorization URLs. - example: OktaSAML - name: - type: string - description: >- - A human-readable name for the Connection. This will - most commonly be the organization's name. - example: Foo Corp - state: - type: string - enum: - - requires_type - - draft - - active - - validating - - inactive - - deleting - description: >- - Indicates whether a Connection is able to - authenticate users. - example: active - status: - type: string - enum: - - linked - - unlinked - description: Deprecated. Use `state` instead. - deprecated: true - example: linked - domains: - type: array - items: - type: object - properties: - id: - type: string - description: Unique identifier for the Connection Domain. - example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A - object: - type: string - description: Distinguishes the Connection Domain object. - const: connection_domain - domain: - type: string - description: The domain value. - example: foo-corp.com - required: - - id - - object - - domain - description: List of Organization Domains. - options: - type: object - properties: - signing_cert: - type: - - string - - 'null' - description: The signing certificate of the SAML connection. - example: null - required: - - signing_cert - description: >- - Configuration options for SAML connections. Only - present for SAML connection types. - 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 - - connection_type - - name - - state - - status - - domains - - created_at - - updated_at - 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: conn_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: conn_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: >- - Pagination cursors for navigating between pages of - results. - required: - - object - - data - - list_metadata - - list_metadata + $ref: '#/components/schemas/ConnectionList' '403': description: Forbidden content: @@ -8241,164 +5892,7 @@ paths: content: application/json: schema: - type: object - properties: - object: - type: string - description: Distinguishes the Connection object. - const: connection - id: - type: string - description: Unique identifier for the Connection. - example: conn_01E4ZCR3C56J083X43JQXF3JK5 - organization_id: - type: string - description: >- - Unique identifier for the Organization in which the - Connection resides. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - connection_type: - type: string - enum: - - Pending - - ADFSSAML - - AdpOidc - - AppleOAuth - - Auth0Migration - - Auth0SAML - - AzureSAML - - BitbucketOAuth - - CasSAML - - ClassLinkSAML - - CleverOIDC - - CloudflareSAML - - CyberArkSAML - - DiscordOAuth - - DuoSAML - - EntraIdOIDC - - GenericOIDC - - GenericSAML - - GitHubOAuth - - GitLabOAuth - - GoogleOAuth - - GoogleOIDC - - GoogleSAML - - IntuitOAuth - - JumpCloudSAML - - KeycloakSAML - - LastPassSAML - - LinkedInOAuth - - LoginGovOidc - - MagicLink - - MicrosoftOAuth - - MiniOrangeSAML - - NetIqSAML - - OktaOIDC - - OktaSAML - - OneLoginSAML - - OracleSAML - - PingFederateSAML - - PingOneSAML - - RipplingSAML - - SalesforceSAML - - ShibbolethGenericSAML - - ShibbolethSAML - - SimpleSamlPhpSAML - - SalesforceOAuth - - SlackOAuth - - TestIdp - - VercelMarketplaceOAuth - - VercelOAuth - - VMwareSAML - - XeroOAuth - description: >- - The type of the SSO Connection used to authenticate the - user. The Connection type may be used to dynamically - generate authorization URLs. - example: OktaSAML - name: - type: string - description: >- - A human-readable name for the Connection. This will most - commonly be the organization's name. - example: Foo Corp - state: - type: string - enum: - - requires_type - - draft - - active - - validating - - inactive - - deleting - description: >- - Indicates whether a Connection is able to authenticate - users. - example: active - status: - type: string - enum: - - linked - - unlinked - description: Deprecated. Use `state` instead. - deprecated: true - example: linked - domains: - type: array - items: - type: object - properties: - id: - type: string - description: Unique identifier for the Connection Domain. - example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A - object: - type: string - description: Distinguishes the Connection Domain object. - const: connection_domain - domain: - type: string - description: The domain value. - example: foo-corp.com - required: - - id - - object - - domain - description: List of Organization Domains. - options: - type: object - properties: - signing_cert: - type: - - string - - 'null' - description: The signing certificate of the SAML connection. - example: null - required: - - signing_cert - description: >- - Configuration options for SAML connections. Only present - for SAML connection types. - 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 - - connection_type - - name - - state - - status - - domains - - created_at - - updated_at + $ref: '#/components/schemas/Connection' '403': description: Forbidden content: @@ -8520,15 +6014,7 @@ paths: content: application/json: schema: - type: object - properties: - url: - type: string - description: The OAuth authorization URL to redirect the user to. - example: >- - https://api.workos.com/data-integrations/q2czJKmVAraSBg8xFpT7M9uR/authorize-redirect - required: - - url + $ref: '#/components/schemas/DataIntegrationAuthorizeUrlResponse' '400': description: Bad Request content: @@ -8614,88 +6100,7 @@ paths: content: application/json: schema: - oneOf: - - type: object - properties: - active: - type: boolean - description: >- - Indicates whether the access token is valid and ready - for use, or if reauthorization is required. - const: true - access_token: - type: object - properties: - object: - type: string - description: Distinguishes the access token object. - const: access_token - access_token: - type: string - description: >- - The OAuth access token for the connected - integration. - example: gho_16C7e42F292c6912E7710c838347Ae178B4a - expires_at: - type: - - string - - 'null' - description: >- - The ISO-8601 formatted timestamp indicating when - the access token expires. - example: '2025-12-31T23:59:59.000Z' - scopes: - type: array - items: - type: string - description: The scopes granted to the access token. - example: - - repo - - user:email - missing_scopes: - type: array - items: - type: string - description: >- - If the integration has requested scopes that - aren't present on the access token, they're listed - here. - example: [] - required: - - object - - access_token - - expires_at - - scopes - - missing_scopes - description: >- - The [access token](/reference/pipes/access-token) - object, present when `active` is `true`. - required: - - active - - access_token - - type: object - properties: - active: - type: boolean - description: >- - Indicates whether the access token is valid and ready - for use, or if reauthorization is required. - const: false - error: - type: string - enum: - - needs_reauthorization - - not_installed - description: >- - - `"not_installed"`: The user does not have the - integration installed. - - - `"needs_reauthorization"`: The user needs to - reauthorize the integration. - example: not_installed - required: - - active - - error + $ref: '#/components/schemas/DataIntegrationAccessTokenResponse' '400': description: Bad Request content: @@ -8800,178 +6205,18 @@ paths: responses: '200': description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/DirectoryList' + '403': + description: Forbidden content: application/json: schema: type: object properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - type: object - properties: - object: - type: string - description: Distinguishes the Directory object. - const: directory - id: - type: string - description: Unique identifier for the Directory. - example: directory_01ECAZ4NV9QMV47GW873HDCX74 - organization_id: - type: string - description: >- - The unique identifier for the Organization in which - the directory resides. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - external_key: - type: string - description: External Key for the Directory. - example: sPa12dwRQ - type: - type: string - enum: - - pending - - azure scim v2.0 - - bamboohr - - breathe hr - - cezanne hr - - cyberark scim v2.0 - - fourth hr - - generic scim v2.0 - - gsuite directory - - hibob - - sailpoint scim v2.0 - - jump cloud scim v2.0 - - okta scim v2.0 - - onelogin scim v2.0 - - people hr - - personio - - pingfederate scim v2.0 - - rippling scim v2.0 - - s3 - - sftp - - sftp workday - - workday - - gusto - - rippling - description: >- - The type of external Directory Provider integrated - with. - example: gsuite directory - state: - type: string - enum: - - requires_type - - linked - - validating - - invalid_credentials - - unlinked - - deleting - description: >- - Describes whether the Directory has been - successfully connected to an external provider. - example: unlinked - name: - type: string - description: The name of the directory. - example: Foo Corp - domain: - type: string - description: The URL associated with an Enterprise Client. - example: foo-corp.com - metadata: - type: object - properties: - users: - type: object - properties: - active: - type: number - description: Count of active directory users. - example: 42 - inactive: - type: number - description: Count of inactive directory users. - example: 3 - required: - - active - - inactive - description: Counts of active and inactive directory users. - groups: - type: number - description: Count of directory groups. - example: 5 - required: - - users - - groups - description: >- - Aggregate counts of directory users and groups - synced from the provider. - 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 - - organization_id - - external_key - - type - - state - - name - - created_at - - updated_at - 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: directory_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: directory_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: >- - Pagination cursors for navigating between pages of - results. - required: - - object - - data - - list_metadata - - list_metadata - '403': - description: Forbidden - content: - application/json: - schema: - type: object - properties: - message: + message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' @@ -9011,124 +6256,7 @@ paths: content: application/json: schema: - type: object - properties: - object: - type: string - description: Distinguishes the Directory object. - const: directory - id: - type: string - description: Unique identifier for the Directory. - example: directory_01ECAZ4NV9QMV47GW873HDCX74 - organization_id: - type: string - description: >- - The unique identifier for the Organization in which the - directory resides. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - external_key: - type: string - description: External Key for the Directory. - example: sPa12dwRQ - type: - type: string - enum: - - pending - - azure scim v2.0 - - bamboohr - - breathe hr - - cezanne hr - - cyberark scim v2.0 - - fourth hr - - generic scim v2.0 - - gsuite directory - - hibob - - sailpoint scim v2.0 - - jump cloud scim v2.0 - - okta scim v2.0 - - onelogin scim v2.0 - - people hr - - personio - - pingfederate scim v2.0 - - rippling scim v2.0 - - s3 - - sftp - - sftp workday - - workday - - gusto - - rippling - description: The type of external Directory Provider integrated with. - example: gsuite directory - state: - type: string - enum: - - requires_type - - linked - - validating - - invalid_credentials - - unlinked - - deleting - description: >- - Describes whether the Directory has been successfully - connected to an external provider. - example: unlinked - name: - type: string - description: The name of the directory. - example: Foo Corp - domain: - type: string - description: The URL associated with an Enterprise Client. - example: foo-corp.com - metadata: - type: object - properties: - users: - type: object - properties: - active: - type: number - description: Count of active directory users. - example: 42 - inactive: - type: number - description: Count of inactive directory users. - example: 3 - required: - - active - - inactive - description: Counts of active and inactive directory users. - groups: - type: number - description: Count of directory groups. - example: 5 - required: - - users - - groups - description: >- - Aggregate counts of directory users and groups synced from - the provider. - 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 - - organization_id - - external_key - - type - - state - - name - - created_at - - updated_at + $ref: '#/components/schemas/Directory' '403': description: Forbidden content: @@ -9276,105 +6404,7 @@ paths: content: application/json: schema: - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - type: object - properties: - object: - type: string - description: Distinguishes the Directory Group object. - const: directory_group - id: - type: string - description: Unique identifier for the Directory Group. - example: directory_group_01E1JJS84MFPPQ3G655FHTKX6Z - idp_id: - type: string - description: >- - Unique identifier for the group, assigned by the - Directory Provider. Different Directory Providers - use different ID formats. - example: 02grqrue4294w24 - directory_id: - type: string - description: >- - The identifier of the Directory the Directory Group - belongs to. - example: directory_01ECAZ4NV9QMV47GW873HDCX74 - organization_id: - type: string - description: >- - The identifier for the Organization in which the - Directory resides. - example: org_01EZTR6WYX1A0DSE2CYMGXQ24Y - name: - type: string - description: The name of the Directory Group. - example: Developers - raw_attributes: - type: object - additionalProperties: {} - description: >- - The raw attributes received from the directory - provider. - 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 - - idp_id - - directory_id - - organization_id - - name - - created_at - - updated_at - 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: directory_group_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: directory_group_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: >- - Pagination cursors for navigating between pages of - results. - required: - - object - - data - - list_metadata - - list_metadata + $ref: '#/components/schemas/DirectoryGroupList' '403': description: Forbidden content: @@ -9435,62 +6465,7 @@ paths: content: application/json: schema: - type: object - properties: - object: - type: string - description: Distinguishes the Directory Group object. - const: directory_group - id: - type: string - description: Unique identifier for the Directory Group. - example: directory_group_01E1JJS84MFPPQ3G655FHTKX6Z - idp_id: - type: string - description: >- - Unique identifier for the group, assigned by the Directory - Provider. Different Directory Providers use different ID - formats. - example: 02grqrue4294w24 - directory_id: - type: string - description: >- - The identifier of the Directory the Directory Group - belongs to. - example: directory_01ECAZ4NV9QMV47GW873HDCX74 - organization_id: - type: string - description: >- - The identifier for the Organization in which the Directory - resides. - example: org_01EZTR6WYX1A0DSE2CYMGXQ24Y - name: - type: string - description: The name of the Directory Group. - example: Developers - raw_attributes: - type: object - additionalProperties: {} - description: The raw attributes received from the directory provider. - 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 - - idp_id - - directory_id - - organization_id - - name - - created_at - - updated_at + $ref: '#/components/schemas/DirectoryGroup' '403': description: Forbidden content: @@ -9600,267 +6575,18 @@ paths: responses: '200': description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/DirectoryUserList' + '403': + description: Forbidden content: application/json: schema: type: object properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - type: object - properties: - object: - type: string - description: Distinguishes the Directory User object. - const: directory_user - id: - type: string - description: Unique identifier for the Directory User. - example: directory_user_01E1JG7J09H96KYP8HM9B0G5SJ - directory_id: - type: string - description: >- - The identifier of the Directory the Directory User - belongs to. - example: directory_01ECAZ4NV9QMV47GW873HDCX74 - organization_id: - type: string - description: >- - The identifier for the Organization in which the - Directory resides. - example: org_01EZTR6WYX1A0DSE2CYMGXQ24Y - idp_id: - type: string - description: >- - Unique identifier for the user, assigned by the - Directory Provider. Different Directory Providers - use different ID formats. - example: '2836' - email: - type: - - string - - 'null' - description: The email address of the user. - example: marcelina.davis@example.com - first_name: - type: - - string - - 'null' - description: The first name of the user. - example: Marcelina - last_name: - type: - - string - - 'null' - description: The last name of the user. - example: Davis - emails: - type: array - items: - type: object - properties: - primary: - type: boolean - description: Whether this is the primary email address. - example: true - type: - type: string - description: The type of email address. - example: work - value: - type: - - string - - 'null' - description: The email address value. - example: marcelina.davis@example.com - description: A list of email addresses for the user. - job_title: - type: - - string - - 'null' - description: The job title of the user. - example: Software Engineer - username: - type: - - string - - 'null' - description: The username of the user. - example: mdavis - state: - type: string - enum: - - active - - suspended - - inactive - description: The state of the user. - example: active - raw_attributes: - type: object - additionalProperties: {} - description: >- - The raw attributes received from the directory - provider. - custom_attributes: - type: object - additionalProperties: {} - description: >- - An object containing the custom attribute mapping - for the Directory Provider. - example: - department: Engineering - job_title: Software Engineer - role: - type: object - properties: - slug: - type: string - description: The slug of the assigned role. - example: admin - required: - - slug - description: The primary role assigned to the user. - roles: - type: array - items: - type: object - properties: - slug: - type: string - description: The slug of the assigned role. - example: admin - required: - - slug - description: All roles assigned to the user. - 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' - groups: - type: array - items: - type: object - properties: - object: - type: string - description: Distinguishes the Directory Group object. - const: directory_group - id: - type: string - description: Unique identifier for the Directory Group. - example: directory_group_01E1JJS84MFPPQ3G655FHTKX6Z - idp_id: - type: string - description: >- - Unique identifier for the group, assigned by - the Directory Provider. Different Directory - Providers use different ID formats. - example: 02grqrue4294w24 - directory_id: - type: string - description: >- - The identifier of the Directory the Directory - Group belongs to. - example: directory_01ECAZ4NV9QMV47GW873HDCX74 - organization_id: - type: string - description: >- - The identifier for the Organization in which - the Directory resides. - example: org_01EZTR6WYX1A0DSE2CYMGXQ24Y - name: - type: string - description: The name of the Directory Group. - example: Developers - raw_attributes: - type: object - additionalProperties: {} - description: >- - The raw attributes received from the directory - provider. - 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 - - idp_id - - directory_id - - organization_id - - name - - created_at - - updated_at - description: The directory groups the user belongs to. - required: - - object - - id - - directory_id - - organization_id - - idp_id - - email - - state - - raw_attributes - - custom_attributes - - created_at - - updated_at - - groups - 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: directory_user_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: directory_user_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: >- - Pagination cursors for navigating between pages of - results. - required: - - object - - data - - list_metadata - - list_metadata - '403': - description: Forbidden - content: - application/json: - schema: - type: object - properties: - message: + message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' @@ -9920,213 +6646,7 @@ paths: content: application/json: schema: - type: object - properties: - object: - type: string - description: Distinguishes the Directory User object. - const: directory_user - id: - type: string - description: Unique identifier for the Directory User. - example: directory_user_01E1JG7J09H96KYP8HM9B0G5SJ - directory_id: - type: string - description: >- - The identifier of the Directory the Directory User belongs - to. - example: directory_01ECAZ4NV9QMV47GW873HDCX74 - organization_id: - type: string - description: >- - The identifier for the Organization in which the Directory - resides. - example: org_01EZTR6WYX1A0DSE2CYMGXQ24Y - idp_id: - type: string - description: >- - Unique identifier for the user, assigned by the Directory - Provider. Different Directory Providers use different ID - formats. - example: '2836' - email: - type: - - string - - 'null' - description: The email address of the user. - example: marcelina.davis@example.com - first_name: - type: - - string - - 'null' - description: The first name of the user. - example: Marcelina - last_name: - type: - - string - - 'null' - description: The last name of the user. - example: Davis - emails: - type: array - items: - type: object - properties: - primary: - type: boolean - description: Whether this is the primary email address. - example: true - type: - type: string - description: The type of email address. - example: work - value: - type: - - string - - 'null' - description: The email address value. - example: marcelina.davis@example.com - description: A list of email addresses for the user. - job_title: - type: - - string - - 'null' - description: The job title of the user. - example: Software Engineer - username: - type: - - string - - 'null' - description: The username of the user. - example: mdavis - state: - type: string - enum: - - active - - suspended - - inactive - description: The state of the user. - example: active - raw_attributes: - type: object - additionalProperties: {} - description: The raw attributes received from the directory provider. - custom_attributes: - type: object - additionalProperties: {} - description: >- - An object containing the custom attribute mapping for the - Directory Provider. - example: - department: Engineering - job_title: Software Engineer - role: - type: object - properties: - slug: - type: string - description: The slug of the assigned role. - example: admin - required: - - slug - description: The primary role assigned to the user. - roles: - type: array - items: - type: object - properties: - slug: - type: string - description: The slug of the assigned role. - example: admin - required: - - slug - description: All roles assigned to the user. - 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' - groups: - type: array - items: - type: object - properties: - object: - type: string - description: Distinguishes the Directory Group object. - const: directory_group - id: - type: string - description: Unique identifier for the Directory Group. - example: directory_group_01E1JJS84MFPPQ3G655FHTKX6Z - idp_id: - type: string - description: >- - Unique identifier for the group, assigned by the - Directory Provider. Different Directory Providers - use different ID formats. - example: 02grqrue4294w24 - directory_id: - type: string - description: >- - The identifier of the Directory the Directory Group - belongs to. - example: directory_01ECAZ4NV9QMV47GW873HDCX74 - organization_id: - type: string - description: >- - The identifier for the Organization in which the - Directory resides. - example: org_01EZTR6WYX1A0DSE2CYMGXQ24Y - name: - type: string - description: The name of the Directory Group. - example: Developers - raw_attributes: - type: object - additionalProperties: {} - description: >- - The raw attributes received from the directory - provider. - 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 - - idp_id - - directory_id - - organization_id - - name - - created_at - - updated_at - description: The directory groups the user belongs to. - required: - - object - - id - - directory_id - - organization_id - - idp_id - - email - - state - - raw_attributes - - custom_attributes - - created_at - - updated_at - - groups + $ref: '#/components/schemas/DirectoryUserWithGroups' '403': description: Forbidden content: @@ -10257,85 +6777,7 @@ paths: content: application/json: schema: - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - type: object - properties: - object: - type: string - description: Distinguishes the Event object. - const: event - id: - type: string - description: Unique identifier for the Event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - description: The type of event that occurred. - example: dsync.user.created - data: - type: object - additionalProperties: {} - description: The event payload. - example: - id: directory_user_01E1JG7J09H96KYP8HM9B0G5SJ - state: active - emails: - - primary: true - value: veda@foo-corp.com - idp_id: '2836' - object: directory_user - username: veda@foo-corp.com - last_name: Torp - first_name: Veda - directory_id: directory_01ECAZ4NV9QMV47GW873HDCX74 - raw_attributes: {} - custom_attributes: {} - created_at: '2021-06-25T19:07:33.155Z' - updated_at: '2021-06-25T19:07:33.155Z' - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - type: object - additionalProperties: {} - description: Additional context about the event. - required: - - object - - id - - event - - data - - created_at - description: The list of records for the current page. - list_metadata: - type: object - properties: - 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: event_01EHZNVPK3SFK441A1RGBFSHRT - required: - - after - description: >- - Pagination cursor for navigating to the next page of - results. - required: - - object - - data - - list_metadata + $ref: '#/components/schemas/EventList' '400': description: Bad Request content: @@ -10435,152 +6877,18 @@ paths: responses: '200': description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/FlagList' + '400': + description: Bad Request content: application/json: schema: type: object properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - type: object - properties: - object: - type: string - description: Distinguishes the Feature Flag object. - const: feature_flag - id: - type: string - description: Unique identifier of the Feature Flag. - example: flag_01EHZNVPK3SFK441A1RGBFSHRT - slug: - type: string - description: A unique key to reference the Feature Flag. - example: advanced-analytics - name: - type: string - description: >- - A descriptive name for the Feature Flag. This field - does not need to be unique. - example: Advanced Analytics - description: - type: - - string - - 'null' - description: A description for the Feature Flag. - example: Enable advanced analytics dashboard feature - owner: - description: The owner of the Feature Flag. - oneOf: - - type: object - properties: - email: - type: string - description: The email address of the flag owner. - example: jane@example.com - first_name: - type: - - string - - 'null' - description: The first name of the flag owner. - example: Jane - last_name: - type: - - string - - 'null' - description: The last name of the flag owner. - example: Doe - required: - - email - - first_name - - last_name - - type: 'null' - tags: - type: array - items: - type: string - description: >- - Labels assigned to the Feature Flag for categorizing - and filtering. - example: - - reports - enabled: - type: boolean - description: >- - Specifies whether the Feature Flag is active for the - current environment. - example: true - default_value: - type: boolean - description: >- - The value returned for users and organizations who - don't match any configured targeting rules. - example: false - 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 - - owner - - tags - - enabled - - default_value - - created_at - - updated_at - 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: flag_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: flag_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: >- - Pagination cursors for navigating between pages of - results. - required: - - object - - data - - list_metadata - '400': - description: Bad Request - content: - application/json: - schema: - type: object - properties: - code: + code: type: string description: The error code identifying the type of error. example: invalid_request_parameters @@ -10620,7 +6928,6 @@ paths: - message tags: - feature-flags - x-feature-flag: flags-management-api /feature-flags/{slug}: get: operationId: FeatureFlagsController_findBySlug @@ -10640,101 +6947,7 @@ paths: content: application/json: schema: - type: object - properties: - object: - type: string - description: Distinguishes the Feature Flag object. - const: feature_flag - id: - type: string - description: Unique identifier of the Feature Flag. - example: flag_01EHZNVPK3SFK441A1RGBFSHRT - slug: - type: string - description: A unique key to reference the Feature Flag. - example: advanced-analytics - name: - type: string - description: >- - A descriptive name for the Feature Flag. This field does - not need to be unique. - example: Advanced Analytics - description: - type: - - string - - 'null' - description: A description for the Feature Flag. - example: Enable advanced analytics dashboard feature - owner: - description: The owner of the Feature Flag. - oneOf: - - type: object - properties: - email: - type: string - description: The email address of the flag owner. - example: jane@example.com - first_name: - type: - - string - - 'null' - description: The first name of the flag owner. - example: Jane - last_name: - type: - - string - - 'null' - description: The last name of the flag owner. - example: Doe - required: - - email - - first_name - - last_name - - type: 'null' - tags: - type: array - items: - type: string - description: >- - Labels assigned to the Feature Flag for categorizing and - filtering. - example: - - reports - enabled: - type: boolean - description: >- - Specifies whether the Feature Flag is active for the - current environment. - example: true - default_value: - type: boolean - description: >- - The value returned for users and organizations who don't - match any configured targeting rules. - example: false - 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 - - owner - - tags - - enabled - - default_value - - created_at - - updated_at + $ref: '#/components/schemas/Flag' '404': description: Not Found content: @@ -10750,7 +6963,6 @@ paths: - message tags: - feature-flags - x-feature-flag: flags-management-api /feature-flags/{slug}/disable: put: operationId: FeatureFlagsController_disableFlag @@ -10865,6 +7077,7 @@ paths: - default_value - created_at - updated_at + x-inline-with-overrides: true '404': description: Not Found content: @@ -10880,7 +7093,6 @@ paths: - message tags: - feature-flags - x-feature-flag: flags-management-api /feature-flags/{slug}/enable: put: operationId: FeatureFlagsController_enableFlag @@ -10995,6 +7207,7 @@ paths: - default_value - created_at - updated_at + x-inline-with-overrides: true '404': description: Not Found content: @@ -11010,7 +7223,6 @@ paths: - message tags: - feature-flags - x-feature-flag: flags-management-api /feature-flags/{slug}/targets/{resourceId}: post: operationId: FlagTargetsController_createTarget @@ -11186,7 +7398,7 @@ paths: organization_id: type: string description: ID of the parent Organization. - example: org_01HE8GSH8FQPASKSY27THRKRBP + example: org_01EHQMYV6MBK39QC5PZXHY59C3 domain: type: string description: Domain for the organization domain. @@ -11233,6 +7445,7 @@ paths: - domain - created_at - updated_at + x-inline-with-overrides: true '409': description: '' content: @@ -11272,66 +7485,7 @@ paths: content: application/json: schema: - type: object - properties: - object: - type: string - description: Distinguishes the organization domain object. - const: organization_domain - id: - type: string - description: Unique identifier of the organization domain. - example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A - organization_id: - type: string - description: ID of the parent Organization. - example: org_01HE8GSH8FQPASKSY27THRKRBP - domain: - type: string - description: Domain for the organization domain. - example: foo-corp.com - state: - type: string - enum: - - failed - - legacy_verified - - pending - - unverified - - verified - description: Verification state of the domain. - example: pending - verification_prefix: - type: string - description: The prefix used in DNS verification. - example: superapp-domain-verification-z3kjny - verification_token: - type: string - description: Validation token to be used in DNS TXT record. - example: m5Oztg3jdK4NJLgs8uIlIprMw - verification_strategy: - type: string - enum: - - dns - - manual - description: Strategy used to verify the domain. - example: dns - 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 - - organization_id - - domain - - created_at - - updated_at + $ref: '#/components/schemas/OrganizationDomainStandAlone' '404': description: Not Found content: @@ -11393,81 +7547,22 @@ paths: responses: '201': description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/OrganizationDomainStandAlone' + '400': + description: Bad Request content: application/json: schema: type: object properties: - object: - type: string - description: Distinguishes the organization domain object. - const: organization_domain - id: - type: string - description: Unique identifier of the organization domain. - example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A - organization_id: - type: string - description: ID of the parent Organization. - example: org_01HE8GSH8FQPASKSY27THRKRBP - domain: - type: string - description: Domain for the organization domain. - example: foo-corp.com - state: - type: string - enum: - - failed - - legacy_verified - - pending - - unverified - - verified - description: Verification state of the domain. - example: pending - verification_prefix: - type: string - description: The prefix used in DNS verification. - example: superapp-domain-verification-z3kjny - verification_token: - type: string - description: Validation token to be used in DNS TXT record. - example: m5Oztg3jdK4NJLgs8uIlIprMw - verification_strategy: - type: string - enum: - - dns - - manual - description: Strategy used to verify the domain. - example: dns - created_at: - format: date-time + code: 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 - - organization_id - - domain - - created_at - - updated_at - '400': - description: Bad Request - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - const: domain_already_verified - message: + description: The error code identifying the type of error. + const: domain_already_verified + message: type: string description: A human-readable description of the error. example: Domain is already verified. @@ -11565,176 +7660,7 @@ paths: content: application/json: schema: - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - type: object - properties: - object: - type: string - description: Distinguishes the Organization object. - const: organization - id: - type: string - description: Unique identifier of the Organization. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - name: - type: string - description: >- - A descriptive name for the Organization. This field - does not need to be unique. - example: Acme Inc. - domains: - type: array - items: - type: object - properties: - object: - type: string - description: Distinguishes the organization domain object. - const: organization_domain - id: - type: string - description: Unique identifier of the organization domain. - example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A - organization_id: - type: string - description: ID of the parent Organization. - example: org_01HE8GSH8FQPASKSY27THRKRBP - domain: - type: string - description: Domain for the organization domain. - example: foo-corp.com - state: - type: string - enum: - - failed - - legacy_verified - - pending - - unverified - - verified - description: Verification state of the domain. - example: pending - verification_prefix: - type: string - description: The prefix used in DNS verification. - example: superapp-domain-verification-z3kjny - verification_token: - type: string - description: Validation token to be used in DNS TXT record. - example: m5Oztg3jdK4NJLgs8uIlIprMw - verification_strategy: - type: string - enum: - - dns - - manual - description: Strategy used to verify the domain. - example: dns - 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 - - organization_id - - domain - - created_at - - updated_at - description: List of Organization Domains. - metadata: - type: object - additionalProperties: - type: string - maxLength: 600 - description: >- - Object containing [metadata](/authkit/metadata) - key/value pairs associated with the Organization. - example: - tier: diamond - propertyNames: - maxLength: 40 - maxProperties: 50 - external_id: - type: - - string - - 'null' - description: The external ID of the Organization. - example: 2fe01467-f7ea-4dd2-8b79-c2b4f56d0191 - stripe_customer_id: - type: string - description: The Stripe customer ID of the Organization. - example: cus_R9qWAGMQ6nGE7V - 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' - allow_profiles_outside_organization: - type: boolean - description: >- - Whether the Organization allows profiles outside of - its managed domains. - example: false - required: - - object - - id - - name - - domains - - metadata - - external_id - - created_at - - updated_at - - allow_profiles_outside_organization - 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: org_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: org_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: >- - Pagination cursors for navigating between pages of - results. - required: - - object - - data - - list_metadata - - list_metadata + $ref: '#/components/schemas/OrganizationList' '422': description: Unprocessable Entity content: @@ -11763,139 +7689,33 @@ paths: $ref: '#/components/schemas/OrganizationDto' responses: '201': - description: Created content: application/json: schema: - type: object - properties: - object: - type: string - description: Distinguishes the Organization object. - const: organization - id: - type: string - description: Unique identifier of the Organization. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - name: - type: string - description: >- - A descriptive name for the Organization. This field does - not need to be unique. - example: Acme Inc. - domains: - type: array - items: - type: object - properties: - object: - type: string - description: Distinguishes the organization domain object. - const: organization_domain - id: - type: string - description: Unique identifier of the organization domain. - example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A - organization_id: - type: string - description: ID of the parent Organization. - example: org_01HE8GSH8FQPASKSY27THRKRBP - domain: - type: string - description: Domain for the organization domain. - example: foo-corp.com - state: - type: string - enum: - - failed - - legacy_verified - - pending - - unverified - - verified - description: Verification state of the domain. - example: pending - verification_prefix: - type: string - description: The prefix used in DNS verification. - example: superapp-domain-verification-z3kjny - verification_token: - type: string - description: Validation token to be used in DNS TXT record. - example: m5Oztg3jdK4NJLgs8uIlIprMw - verification_strategy: - type: string - enum: - - dns - - manual - description: Strategy used to verify the domain. - example: dns - 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 - - organization_id - - domain - - created_at - - updated_at - description: List of Organization Domains. - metadata: - type: object - additionalProperties: - type: string - maxLength: 600 - description: >- - Object containing [metadata](/authkit/metadata) key/value - pairs associated with the Organization. - example: - tier: diamond - propertyNames: - maxLength: 40 - maxProperties: 50 - external_id: - type: - - string - - 'null' - description: The external ID of the Organization. - example: 2fe01467-f7ea-4dd2-8b79-c2b4f56d0191 - stripe_customer_id: - type: string - description: The Stripe customer ID of the Organization. - example: cus_R9qWAGMQ6nGE7V - 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' - allow_profiles_outside_organization: - type: boolean - description: >- - Whether the Organization allows profiles outside of its - managed domains. - example: false - required: - - object - - id - - name - - domains - - metadata - - external_id - - created_at - - updated_at - - allow_profiles_outside_organization + $ref: '#/components/schemas/Organization' + example: + object: organization + name: Foo Corp + domains: + - object: organization_domain + id: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A + organization_id: org_01HE8GSH8FQPASKSY27THRKRBP + domain: foo-corp.com + state: pending + verification_prefix: superapp-domain-verification-z3kjny + verification_token: m5Oztg3jdK4NJLgs8uIlIprMw + verification_strategy: dns + created_at: '2026-01-15T12:00:00.000Z' + updated_at: '2026-01-15T12:00:00.000Z' + metadata: + tier: diamond + stripe_customer_id: cus_R9qWAGMQ6nGE7V + created_at: '2026-01-15T12:00:00.000Z' + updated_at: '2026-01-15T12:00:00.000Z' + allow_profiles_outside_organization: false + id: org_01EHWNCE74X7JSDV0X3SZ3KJNY + external_id: ext_12345 + description: Created '400': description: Bad Request content: @@ -11979,135 +7799,7 @@ paths: content: application/json: schema: - type: object - properties: - object: - type: string - description: Distinguishes the Organization object. - const: organization - id: - type: string - description: Unique identifier of the Organization. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - name: - type: string - description: >- - A descriptive name for the Organization. This field does - not need to be unique. - example: Acme Inc. - domains: - type: array - items: - type: object - properties: - object: - type: string - description: Distinguishes the organization domain object. - const: organization_domain - id: - type: string - description: Unique identifier of the organization domain. - example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A - organization_id: - type: string - description: ID of the parent Organization. - example: org_01HE8GSH8FQPASKSY27THRKRBP - domain: - type: string - description: Domain for the organization domain. - example: foo-corp.com - state: - type: string - enum: - - failed - - legacy_verified - - pending - - unverified - - verified - description: Verification state of the domain. - example: pending - verification_prefix: - type: string - description: The prefix used in DNS verification. - example: superapp-domain-verification-z3kjny - verification_token: - type: string - description: Validation token to be used in DNS TXT record. - example: m5Oztg3jdK4NJLgs8uIlIprMw - verification_strategy: - type: string - enum: - - dns - - manual - description: Strategy used to verify the domain. - example: dns - 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 - - organization_id - - domain - - created_at - - updated_at - description: List of Organization Domains. - metadata: - type: object - additionalProperties: - type: string - maxLength: 600 - description: >- - Object containing [metadata](/authkit/metadata) key/value - pairs associated with the Organization. - example: - tier: diamond - propertyNames: - maxLength: 40 - maxProperties: 50 - external_id: - type: - - string - - 'null' - description: The external ID of the Organization. - example: 2fe01467-f7ea-4dd2-8b79-c2b4f56d0191 - stripe_customer_id: - type: string - description: The Stripe customer ID of the Organization. - example: cus_R9qWAGMQ6nGE7V - 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' - allow_profiles_outside_organization: - type: boolean - description: >- - Whether the Organization allows profiles outside of its - managed domains. - example: false - required: - - object - - id - - name - - domains - - metadata - - external_id - - created_at - - updated_at - - allow_profiles_outside_organization + $ref: '#/components/schemas/Organization' '404': description: Not Found content: @@ -12141,146 +7833,18 @@ paths: responses: '200': description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Organization' + '404': + description: Not Found content: application/json: schema: type: object properties: - object: - type: string - description: Distinguishes the Organization object. - const: organization - id: - type: string - description: Unique identifier of the Organization. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - name: - type: string - description: >- - A descriptive name for the Organization. This field does - not need to be unique. - example: Acme Inc. - domains: - type: array - items: - type: object - properties: - object: - type: string - description: Distinguishes the organization domain object. - const: organization_domain - id: - type: string - description: Unique identifier of the organization domain. - example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A - organization_id: - type: string - description: ID of the parent Organization. - example: org_01HE8GSH8FQPASKSY27THRKRBP - domain: - type: string - description: Domain for the organization domain. - example: foo-corp.com - state: - type: string - enum: - - failed - - legacy_verified - - pending - - unverified - - verified - description: Verification state of the domain. - example: pending - verification_prefix: - type: string - description: The prefix used in DNS verification. - example: superapp-domain-verification-z3kjny - verification_token: - type: string - description: Validation token to be used in DNS TXT record. - example: m5Oztg3jdK4NJLgs8uIlIprMw - verification_strategy: - type: string - enum: - - dns - - manual - description: Strategy used to verify the domain. - example: dns - 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 - - organization_id - - domain - - created_at - - updated_at - description: List of Organization Domains. - metadata: - type: object - additionalProperties: - type: string - maxLength: 600 - description: >- - Object containing [metadata](/authkit/metadata) key/value - pairs associated with the Organization. - example: - tier: diamond - propertyNames: - maxLength: 40 - maxProperties: 50 - external_id: - type: - - string - - 'null' - description: The external ID of the Organization. - example: 2fe01467-f7ea-4dd2-8b79-c2b4f56d0191 - stripe_customer_id: - type: string - description: The Stripe customer ID of the Organization. - example: cus_R9qWAGMQ6nGE7V - 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' - allow_profiles_outside_organization: - type: boolean - description: >- - Whether the Organization allows profiles outside of its - managed domains. - example: false - required: - - object - - id - - name - - domains - - metadata - - external_id - - created_at - - updated_at - - allow_profiles_outside_organization - '404': - description: Not Found - content: - application/json: - schema: - type: object - properties: - message: + message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' @@ -12308,139 +7872,33 @@ paths: $ref: '#/components/schemas/UpdateOrganizationDto' responses: '200': - description: OK content: application/json: schema: - type: object - properties: - object: - type: string - description: Distinguishes the Organization object. - const: organization - id: - type: string - description: Unique identifier of the Organization. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - name: - type: string - description: >- - A descriptive name for the Organization. This field does - not need to be unique. - example: Acme Inc. - domains: - type: array - items: - type: object - properties: - object: - type: string - description: Distinguishes the organization domain object. - const: organization_domain - id: - type: string - description: Unique identifier of the organization domain. - example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A - organization_id: - type: string - description: ID of the parent Organization. - example: org_01HE8GSH8FQPASKSY27THRKRBP - domain: - type: string - description: Domain for the organization domain. - example: foo-corp.com - state: - type: string - enum: - - failed - - legacy_verified - - pending - - unverified - - verified - description: Verification state of the domain. - example: pending - verification_prefix: - type: string - description: The prefix used in DNS verification. - example: superapp-domain-verification-z3kjny - verification_token: - type: string - description: Validation token to be used in DNS TXT record. - example: m5Oztg3jdK4NJLgs8uIlIprMw - verification_strategy: - type: string - enum: - - dns - - manual - description: Strategy used to verify the domain. - example: dns - 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 - - organization_id - - domain - - created_at - - updated_at - description: List of Organization Domains. - metadata: - type: object - additionalProperties: - type: string - maxLength: 600 - description: >- - Object containing [metadata](/authkit/metadata) key/value - pairs associated with the Organization. - example: - tier: diamond - propertyNames: - maxLength: 40 - maxProperties: 50 - external_id: - type: - - string - - 'null' - description: The external ID of the Organization. - example: 2fe01467-f7ea-4dd2-8b79-c2b4f56d0191 - stripe_customer_id: - type: string - description: The Stripe customer ID of the Organization. - example: cus_R9qWAGMQ6nGE7V - 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' - allow_profiles_outside_organization: - type: boolean - description: >- - Whether the Organization allows profiles outside of its - managed domains. - example: false - required: - - object - - id - - name - - domains - - metadata - - external_id - - created_at - - updated_at - - allow_profiles_outside_organization + $ref: '#/components/schemas/Organization' + example: + object: organization + name: Foo Corp + domains: + - object: organization_domain + id: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A + organization_id: org_01HE8GSH8FQPASKSY27THRKRBP + domain: foo-corp.com + state: pending + verification_prefix: superapp-domain-verification-z3kjny + verification_token: m5Oztg3jdK4NJLgs8uIlIprMw + verification_strategy: dns + created_at: '2026-01-15T12:00:00.000Z' + updated_at: '2026-01-15T12:00:00.000Z' + metadata: + tier: diamond + stripe_customer_id: cus_R9qWAGMQ6nGE7V + created_at: '2026-01-15T12:00:00.000Z' + updated_at: '2026-01-15T12:00:00.000Z' + allow_profiles_outside_organization: false + id: org_01EHZNVPK3SFK441A1RGBFSHRT + external_id: 2fe01467-f7ea-4dd2-8b79-c2b4f56d0191 + description: OK '400': description: Bad Request content: @@ -12598,82 +8056,7 @@ paths: content: application/json: schema: - type: object - properties: - organization_id: - type: string - description: Unique identifier of the Organization. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - retention_period_in_days: - type: number - description: >- - The number of days Audit Log events will be retained - before being permanently deleted. - example: 30 - state: - type: string - enum: - - active - - inactive - - disabled - description: >- - The current state of the audit log configuration for the - organization. - example: active - log_stream: - type: object - properties: - id: - type: string - description: Unique identifier of the Audit Log Stream. - example: als_01EHZNVPK3SFK441A1RGBFSHRT - type: - type: string - enum: - - AzureSentinel - - Datadog - - GenericHttps - - GoogleCloudStorage - - S3 - - Splunk - description: The type of the Audit Log Stream destination. - example: Datadog - state: - type: string - enum: - - active - - inactive - - error - - invalid - description: The current state of the Audit Log Stream. - example: active - last_synced_at: - type: - - string - - 'null' - description: >- - ISO-8601 timestamp of when the last event was - successfully synced, or null if no events have been - synced. - example: '2026-01-15T12:00:00.000Z' - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - required: - - id - - type - - state - - last_synced_at - - created_at - description: >- - The Audit Log Stream currently configured for the - organization, if any. - required: - - organization_id - - retention_period_in_days - - state + $ref: '#/components/schemas/AuditLogConfiguration' '404': description: Not Found content: @@ -12835,257 +8218,75 @@ paths: responses: '200': description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ApiKeyList' + '404': + description: Not Found content: application/json: schema: type: object properties: - object: + message: type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - type: object - properties: - object: - type: string - description: Distinguishes the API Key object. - const: api_key - id: - type: string - description: Unique identifier of the API Key. - example: api_key_01EHZNVPK3SFK441A1RGBFSHRT - owner: - type: object - properties: - type: - type: string - description: The type of the API Key owner. - example: organization - const: organization - id: - type: string - description: Unique identifier of the API Key owner. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - required: - - type - - id - description: The entity that owns the API Key. - name: - type: string - description: A descriptive name for the API Key. - example: Production API Key - obfuscated_value: - type: string - description: An obfuscated representation of the API Key value. - example: sk_...3456 - last_used_at: - type: - - string - - 'null' - description: Timestamp of when the API Key was last used. - example: null - permissions: - type: array - items: - type: string - description: The permission slugs assigned to the API Key. - 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: - - object - - id - - owner - - name - - obfuscated_value - - last_used_at - - permissions - - created_at - - updated_at - 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: api_key_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: api_key_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: >- - Pagination cursors for navigating between pages of - results. - required: - - object - - data - - list_metadata - '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 - tags: - - organizations.api_keys - x-feature-flag: api-keys-management-api - post: - operationId: OrganizationApiKeysController_create - summary: Create an API key for an organization - description: Create a new API key for an organization. - parameters: - - name: organizationId - required: true - in: path - description: Unique identifier of the Organization. - schema: - type: string - example: org_01EHZNVPK3SFK441A1RGBFSHRT - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreateOrganizationApiKeyDto' - responses: - '201': - description: Created - content: - application/json: - schema: - type: object - properties: - object: - type: string - description: Distinguishes the API Key object. - const: api_key - id: - type: string - description: Unique identifier of the API Key. - example: api_key_01EHZNVPK3SFK441A1RGBFSHRT - owner: - type: object - properties: - type: - type: string - description: The type of the API Key owner. - example: organization - const: organization - id: - type: string - description: Unique identifier of the API Key owner. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - required: - - type - - id - description: The entity that owns the API Key. - name: - type: string - description: A descriptive name for the API Key. - example: Production API Key - obfuscated_value: - type: string - description: An obfuscated representation of the API Key value. - example: sk_...3456 - last_used_at: - type: - - string - - 'null' - description: Timestamp of when the API Key was last used. - example: null - permissions: - type: array - items: - type: string - description: The permission slugs assigned to the API Key. - 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' - value: - type: string - description: >- - The full API Key value. Only returned once at creation - time. - example: sk_abcdefghijklmnop123456 - required: - - object - - id - - owner - - name - - obfuscated_value - - last_used_at - - permissions - - created_at - - updated_at - - value - '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: Validation failed. - errors: + description: A human-readable description of the error. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + required: + - message + tags: + - organizations.api_keys + post: + operationId: OrganizationApiKeysController_create + summary: Create an API key for an organization + description: Create a new API key for an organization. + parameters: + - name: organizationId + required: true + in: path + description: Unique identifier of the Organization. + schema: + type: string + example: org_01EHZNVPK3SFK441A1RGBFSHRT + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateOrganizationApiKeyDto' + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/ApiKeyWithValue' + '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: Validation failed. + errors: type: array items: type: object @@ -13107,7 +8308,6 @@ paths: - errors tags: - organizations.api_keys - x-feature-flag: api-keys-management-api /organizations/{organizationId}/feature-flags: get: operationId: OrganizationFeatureFlagsController_list @@ -13169,141 +8369,7 @@ paths: content: application/json: schema: - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - type: object - properties: - object: - type: string - description: Distinguishes the Feature Flag object. - const: feature_flag - id: - type: string - description: Unique identifier of the Feature Flag. - example: flag_01EHZNVPK3SFK441A1RGBFSHRT - slug: - type: string - description: A unique key to reference the Feature Flag. - example: advanced-analytics - name: - type: string - description: >- - A descriptive name for the Feature Flag. This field - does not need to be unique. - example: Advanced Analytics - description: - type: - - string - - 'null' - description: A description for the Feature Flag. - example: Enable advanced analytics dashboard feature - owner: - description: The owner of the Feature Flag. - oneOf: - - type: object - properties: - email: - type: string - description: The email address of the flag owner. - example: jane@example.com - first_name: - type: - - string - - 'null' - description: The first name of the flag owner. - example: Jane - last_name: - type: - - string - - 'null' - description: The last name of the flag owner. - example: Doe - required: - - email - - first_name - - last_name - - type: 'null' - tags: - type: array - items: - type: string - description: >- - Labels assigned to the Feature Flag for categorizing - and filtering. - example: - - reports - enabled: - type: boolean - description: >- - Specifies whether the Feature Flag is active for the - current environment. - example: true - default_value: - type: boolean - description: >- - The value returned for users and organizations who - don't match any configured targeting rules. - example: false - 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 - - owner - - tags - - enabled - - default_value - - created_at - - updated_at - 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: flag_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: flag_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: >- - Pagination cursors for navigating between pages of - results. - required: - - object - - data - - list_metadata + $ref: '#/components/schemas/FlagList' '404': description: Not Found content: @@ -13337,15 +8403,7 @@ paths: content: application/json: schema: - type: object - properties: - link: - type: string - description: An ephemeral link to initiate the Admin Portal. - example: >- - https://setup.workos.com?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... - required: - - link + $ref: '#/components/schemas/PortalLinkResponse' '400': description: Bad Request content: @@ -13472,59 +8530,7 @@ paths: content: application/json: schema: - type: object - properties: - verdict: - type: string - enum: - - allow - - block - - challenge - description: The verdict of the risk assessment. - example: block - reason: - type: string - description: A human-readable reason for the verdict. - example: Detected enabled Radar control - attempt_id: - type: string - description: Unique identifier of the authentication attempt. - example: radar_att_01HZBC6N1EB1ZY7KG32X - control: - type: string - enum: - - bot_detection - - brute_force_attack - - credential_stuffing - - domain_sign_up_rate_limit - - ip_sign_up_rate_limit - - impossible_travel - - repeat_sign_up - - stale_account - - unrecognized_device - - restriction - description: >- - The Radar control that triggered the verdict. Only present - if the verdict is `block` or `challenge`. - example: bot_detection - blocklist_type: - type: string - enum: - - ip_address - - domain - - email - - device - - user_agent - - device_fingerprint - - country - description: >- - The type of blocklist entry that triggered the verdict. - Only present if the control is `restriction`. - example: ip_address - required: - - verdict - - reason - - attempt_id + $ref: '#/components/schemas/RadarStandaloneResponse' '400': description: Standalone radar is not enabled. content: @@ -13661,12 +8667,7 @@ paths: content: application/json: schema: - type: object - properties: - message: - type: string - description: A message indicating the entry already exists. - example: Entry already present in list + $ref: '#/components/schemas/RadarListEntryAlreadyPresentResponse' '201': description: Created '204': @@ -13955,16 +8956,7 @@ paths: content: application/json: schema: - type: object - properties: - url: - type: string - format: uri - description: An OAuth 2.0 authorization URL. - example: >- - https://accounts.google.com/o/oauth2/v2/auth?client_id=example&redirect_uri=https%3A%2F%2Fapi.workos.com%2Fsso%2Fcallback&response_type=code&scope=openid%20profile%20email - required: - - url + $ref: '#/components/schemas/SsoAuthorizeUrlResponse' '302': headers: Location: @@ -13998,61 +8990,7 @@ paths: content: application/json: schema: - type: object - properties: - keys: - type: array - items: - type: object - properties: - alg: - type: string - description: Algorithm. - const: RS256 - kty: - type: string - description: Key type. - const: RSA - use: - type: string - description: Key use (signature). - const: sig - x5c: - type: array - items: - type: string - description: X.509 certificate chain. - example: - - >- - MIIDQjCCAiqgAwIBAgIGATz/FuLiMA0GCSqGSIb3DQEBCwUA... - 'n': - type: string - description: RSA modulus. - example: 0vx7agoebGc...eKnNs - e: - type: string - description: RSA exponent. - example: AQAB - kid: - type: string - description: Key ID. - example: key_01HXYZ123456789ABCDEFGHIJ - x5t#S256: - type: string - description: X.509 certificate SHA-256 thumbprint. - example: ZjQzYjI0OT...NmNjU0 - required: - - alg - - kty - - use - - x5c - - 'n' - - e - - kid - - x5t#S256 - description: The public keys used for verifying access tokens. - required: - - keys + $ref: '#/components/schemas/JwksResponse' '404': description: Not Found content: @@ -14151,26 +9089,7 @@ paths: content: application/json: schema: - type: object - properties: - logout_url: - type: string - description: >- - The URL to redirect the user to in order to log out - ([Logout Redirect](/reference/sso/logout) endpoint ready - to use). - example: >- - https://auth.workos.com/sso/logout?token=eyJhbGciOiJSUzI1NiJ9 - logout_token: - type: string - description: >- - The logout token to be used in the [Logout - Redirect](/reference/sso/logout) endpoint. - example: >- - eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwcm9maWxlX2lkIjoicHJvZl8wMUdXUTFHMEgyRk02QVNFRjBIUzEzSENXOS0zMDRrZzAzZyIsImV4cCI6IjE1MTYyMzkwMjIifQ.Wru9Qlnf5DpohtGCKhZU4cVOd3zpiu7QQ-XEX--5A_4 - required: - - logout_url - - logout_token + $ref: '#/components/schemas/SsoLogoutAuthorizeResponse' '201': description: Created '400': @@ -14240,150 +9159,7 @@ paths: content: application/json: schema: - type: object - properties: - object: - type: string - description: Distinguishes the profile object. - example: profile - const: profile - id: - type: string - description: Unique identifier of the profile. - example: prof_01DMC79VCBZ0NY2099737PSVF1 - organization_id: - type: - - string - - 'null' - description: The ID of the organization the user belongs to. - example: org_01EHQMYV6MBK39QC5PZXHY59C3 - connection_id: - type: string - description: The ID of the SSO connection used for authentication. - example: conn_01E4ZCR3C56J083X43JQXF3JK5 - connection_type: - type: string - enum: - - Pending - - ADFSSAML - - AdpOidc - - AppleOAuth - - Auth0Migration - - Auth0SAML - - AzureSAML - - BitbucketOAuth - - CasSAML - - ClassLinkSAML - - CleverOIDC - - CloudflareSAML - - CyberArkSAML - - DiscordOAuth - - DuoSAML - - EntraIdOIDC - - GenericOIDC - - GenericSAML - - GitHubOAuth - - GitLabOAuth - - GoogleOAuth - - GoogleOIDC - - GoogleSAML - - IntuitOAuth - - JumpCloudSAML - - KeycloakSAML - - LastPassSAML - - LinkedInOAuth - - LoginGovOidc - - MagicLink - - MicrosoftOAuth - - MiniOrangeSAML - - NetIqSAML - - OktaOIDC - - OktaSAML - - OneLoginSAML - - OracleSAML - - PingFederateSAML - - PingOneSAML - - RipplingSAML - - SalesforceSAML - - ShibbolethGenericSAML - - ShibbolethSAML - - SimpleSamlPhpSAML - - SalesforceOAuth - - SlackOAuth - - TestIdp - - VercelMarketplaceOAuth - - VercelOAuth - - VMwareSAML - - XeroOAuth - description: The type of SSO connection. - example: GoogleOAuth - idp_id: - type: string - description: The user's unique identifier from the identity provider. - example: '103456789012345678901' - email: - type: string - description: The user's email address. - example: todd@example.com - first_name: - type: - - string - - 'null' - description: The user's first name. - example: Todd - last_name: - type: - - string - - 'null' - description: The user's last name. - example: Rundgren - role: - description: >- - The role assigned to the user within the organization, if - applicable. - oneOf: - - type: object - properties: - slug: - type: string - description: The slug of the assigned role. - example: admin - required: - - slug - - type: 'null' - groups: - type: array - items: - type: string - description: >- - The groups the user belongs to, as returned by the - identity provider. - example: - - Engineering - - Admins - custom_attributes: - type: object - additionalProperties: {} - description: >- - Custom attribute mappings defined for the connection, - returned as key-value pairs. - raw_attributes: - type: object - additionalProperties: {} - description: >- - The complete set of raw attributes returned by the - identity provider. - required: - - object - - id - - organization_id - - connection_id - - connection_type - - idp_id - - email - - first_name - - last_name - - raw_attributes + $ref: '#/components/schemas/Profile' '401': description: Unauthorized content: @@ -14462,215 +9238,7 @@ paths: content: application/json: schema: - type: object - properties: - token_type: - type: string - description: The type of token issued. - const: Bearer - access_token: - type: string - description: >- - An access token that can be exchanged for a user profile. - Access tokens are short-lived — see the `expires_in` field - for the exact lifetime. - example: eyJhbGciOiJSUzI1NiIsImtpZCI6InNzby... - expires_in: - type: number - description: The lifetime of the access token in seconds. - example: 600 - profile: - type: object - properties: - object: - type: string - description: Distinguishes the profile object. - example: profile - const: profile - id: - type: string - description: Unique identifier of the profile. - example: prof_01DMC79VCBZ0NY2099737PSVF1 - organization_id: - type: - - string - - 'null' - description: The ID of the organization the user belongs to. - example: org_01EHQMYV6MBK39QC5PZXHY59C3 - connection_id: - type: string - description: The ID of the SSO connection used for authentication. - example: conn_01E4ZCR3C56J083X43JQXF3JK5 - connection_type: - type: string - enum: - - Pending - - ADFSSAML - - AdpOidc - - AppleOAuth - - Auth0Migration - - Auth0SAML - - AzureSAML - - BitbucketOAuth - - CasSAML - - ClassLinkSAML - - CleverOIDC - - CloudflareSAML - - CyberArkSAML - - DiscordOAuth - - DuoSAML - - EntraIdOIDC - - GenericOIDC - - GenericSAML - - GitHubOAuth - - GitLabOAuth - - GoogleOAuth - - GoogleOIDC - - GoogleSAML - - IntuitOAuth - - JumpCloudSAML - - KeycloakSAML - - LastPassSAML - - LinkedInOAuth - - LoginGovOidc - - MagicLink - - MicrosoftOAuth - - MiniOrangeSAML - - NetIqSAML - - OktaOIDC - - OktaSAML - - OneLoginSAML - - OracleSAML - - PingFederateSAML - - PingOneSAML - - RipplingSAML - - SalesforceSAML - - ShibbolethGenericSAML - - ShibbolethSAML - - SimpleSamlPhpSAML - - SalesforceOAuth - - SlackOAuth - - TestIdp - - VercelMarketplaceOAuth - - VercelOAuth - - VMwareSAML - - XeroOAuth - description: The type of SSO connection. - example: GoogleOAuth - idp_id: - type: string - description: >- - The user's unique identifier from the identity - provider. - example: '103456789012345678901' - email: - type: string - description: The user's email address. - example: todd@example.com - first_name: - type: - - string - - 'null' - description: The user's first name. - example: Todd - last_name: - type: - - string - - 'null' - description: The user's last name. - example: Rundgren - role: - description: >- - The role assigned to the user within the organization, - if applicable. - oneOf: - - type: object - properties: - slug: - type: string - description: The slug of the assigned role. - example: admin - required: - - slug - - type: 'null' - groups: - type: array - items: - type: string - description: >- - The groups the user belongs to, as returned by the - identity provider. - example: - - Engineering - - Admins - custom_attributes: - type: object - additionalProperties: {} - description: >- - Custom attribute mappings defined for the connection, - returned as key-value pairs. - raw_attributes: - type: object - additionalProperties: {} - description: >- - The complete set of raw attributes returned by the - identity provider. - required: - - object - - id - - organization_id - - connection_id - - connection_type - - idp_id - - email - - first_name - - last_name - - raw_attributes - description: The user profile returned by the identity provider. - oauth_tokens: - type: object - properties: - provider: - type: string - description: The OAuth provider used for authentication. - example: GoogleOAuth - refresh_token: - type: string - description: The refresh token from the OAuth provider. - example: 1//04g... - access_token: - type: string - description: The access token from the OAuth provider. - example: ya29.a0ARrdaM... - expires_at: - type: number - description: The timestamp at which the access token expires. - example: 1735141800 - scopes: - type: array - items: - type: string - description: >- - A list of OAuth scopes for which the access token is - authorized. - example: - - profile - - email - - openid - required: - - provider - - refresh_token - - access_token - - expires_at - - scopes - description: >- - OAuth tokens issued by the identity provider, if - available. - required: - - token_type - - access_token - - expires_in - - profile + $ref: '#/components/schemas/SsoTokenResponse' '201': description: Created '400': @@ -15090,216 +9658,7 @@ paths: content: application/json: schema: - type: object - properties: - user: - type: object - properties: - object: - type: string - description: Distinguishes the user object. - const: user - id: - type: string - description: The unique ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - first_name: - type: - - string - - 'null' - description: The first name of the user. - example: Marcelina - last_name: - type: - - string - - 'null' - description: The last name of the user. - example: Davis - profile_picture_url: - type: - - string - - 'null' - description: A URL reference to an image representing the user. - example: https://workoscdn.com/images/v1/123abc - email: - type: string - description: The email address of the user. - example: marcelina.davis@example.com - email_verified: - type: boolean - description: Whether the user's email has been verified. - example: true - external_id: - type: - - string - - 'null' - description: The external ID of the user. - example: f1ffa2b2-c20b-4d39-be5c-212726e11222 - metadata: - type: object - additionalProperties: - type: string - maxLength: 600 - description: >- - Object containing metadata key/value pairs associated - with the user. - example: - timezone: America/New_York - propertyNames: - maxLength: 40 - maxProperties: 50 - last_sign_in_at: - format: date-time - type: - - string - - 'null' - description: The timestamp when the user last signed in. - example: '2025-06-25T19:07:33.155Z' - locale: - type: - - string - - 'null' - description: The user's preferred locale. - example: en-US - 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 - - first_name - - last_name - - profile_picture_url - - email - - email_verified - - external_id - - last_sign_in_at - - created_at - - updated_at - description: The corresponding [user](/reference/authkit/user) object. - organization_id: - type: string - description: >- - The ID of the organization the user selected to sign in - to. - example: org_01H945H0YD4F97JN9MATX7BYAG - authkit_authorization_code: - type: string - description: >- - An authorization code that can be exchanged for tokens by - a different application. - example: authkit_authz_code_abc123 - access_token: - type: string - description: A JWT containing information about the current session. - example: eyJhb.nNzb19vaWRjX2tleV9.lc5Uk4yWVk5In0 - refresh_token: - type: string - description: >- - [Exchange this - token](/reference/authkit/authentication/refresh-token) - for a new access token. - example: yAjhKk123NLIjdrBdGZPf8pLIDvK - authentication_method: - type: string - enum: - - SSO - - Password - - Passkey - - AppleOAuth - - BitbucketOAuth - - CrossAppAuth - - DiscordOAuth - - ExternalAuth - - GitHubOAuth - - GitLabOAuth - - GoogleOAuth - - IntuitOAuth - - LinkedInOAuth - - MicrosoftOAuth - - SalesforceOAuth - - SlackOAuth - - VercelMarketplaceOAuth - - VercelOAuth - - XeroOAuth - - MagicAuth - - Impersonation - - MigratedSession - description: The authentication method used to initiate the session. - example: SSO - impersonator: - type: object - properties: - email: - type: string - description: >- - The email address of the WorkOS Dashboard user who is - impersonating the user. - example: admin@foocorp.com - reason: - type: - - string - - 'null' - description: >- - The justification the impersonator gave for - impersonating the user. - example: Investigating an issue with the customer's account. - required: - - email - - reason - description: >- - Information about the impersonator if this session was - created via impersonation. - oauth_tokens: - type: object - properties: - provider: - type: string - description: The OAuth provider used for authentication. - example: GoogleOAuth - refresh_token: - type: string - description: The refresh token from the OAuth provider. - example: 1//04g... - access_token: - type: string - description: The access token from the OAuth provider. - example: ya29.a0ARrdaM... - expires_at: - type: number - description: The timestamp at which the access token expires. - example: 1735141800 - scopes: - type: array - items: - type: string - description: >- - A list of OAuth scopes for which the access token is - authorized. - example: - - profile - - email - - openid - required: - - provider - - refresh_token - - access_token - - expires_at - - scopes - description: >- - The OAuth tokens from the identity provider, if - applicable. - required: - - user - - access_token - - refresh_token + $ref: '#/components/schemas/UserlandAuthenticateResponse' '400': description: Bad Request content: @@ -16102,41 +10461,7 @@ paths: content: application/json: schema: - type: object - properties: - device_code: - type: string - description: The device verification code. - example: >- - CVE2wOfIFK4vhmiDBntpX9s8KT2f0qngpWYL0LGy9HxYgBRXUKIUkZB9BgIFho5h - user_code: - type: string - description: The end-user verification code. - example: BCDF-GHJK - verification_uri: - type: string - format: uri - description: The end-user verification URI. - example: https://authkit_domain/device - verification_uri_complete: - type: string - format: uri - description: Verification URI that includes the user code. - example: https://authkit_domain/device?user_code=BCDF-GHJK - expires_in: - type: number - description: Lifetime in seconds of the codes. - example: 300 - interval: - type: number - description: Minimum polling interval in seconds. - default: 5 - example: 5 - required: - - device_code - - user_code - - verification_uri - - expires_in + $ref: '#/components/schemas/DeviceAuthorizationResponse' '400': description: Invalid request parameters. content: @@ -16192,45 +10517,22 @@ paths: responses: '201': description: CORS origin created successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/CorsOriginResponse' + '409': + description: Duplicate CORS origin. content: application/json: schema: type: object properties: - object: - type: string - description: Distinguishes the CORS origin object. - example: cors_origin - id: + code: type: string - description: Unique identifier of the CORS origin. - example: cors_origin_01HXYZ123456789ABCDEFGHIJ - origin: - type: string - description: The origin URL. - example: https://example.com - created_at: - type: string - format: date-time - description: Timestamp when the CORS origin was created. - example: '2026-01-15T12:00:00.000Z' - updated_at: - type: string - format: date-time - description: Timestamp when the CORS origin was last updated. - example: '2026-01-15T12:00:00.000Z' - '409': - description: Duplicate CORS origin. - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code. - example: duplicate_cors_origin - message: + description: The error code. + example: duplicate_cors_origin + message: type: string description: A human-readable error message. example: CORS origin already exists. @@ -16280,52 +10582,7 @@ paths: content: application/json: schema: - type: object - properties: - object: - type: string - description: Distinguishes the email verification object. - const: email_verification - id: - type: string - description: The unique ID of the email verification code. - example: email_verification_01E4ZCR3C56J083X43JQXF3JK5 - user_id: - type: string - description: The unique ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: string - description: The email address of the user. - example: marcelina.davis@example.com - expires_at: - format: date-time - type: string - description: The timestamp when the email verification code expires. - example: '2026-01-15T12:00:00.000Z' - 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' - code: - type: string - description: The code used to verify the email. - example: '123456' - required: - - object - - id - - user_id - - email - - expires_at - - created_at - - updated_at - - code + $ref: '#/components/schemas/EmailVerification' '404': description: Not Found content: @@ -16461,113 +10718,7 @@ paths: type: array description: The list of records for the current page. items: - type: object - properties: - object: - type: string - description: Distinguishes the invitation object. - const: invitation - id: - type: string - description: The unique ID of the invitation. - example: invitation_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: string - description: The email address of the recipient. - example: marcelina.davis@example.com - state: - type: string - enum: - - pending - - accepted - - expired - - revoked - description: The state of the invitation. - example: pending - accepted_at: - format: date-time - type: - - string - - 'null' - description: >- - The timestamp when the invitation was accepted, - or null if not yet accepted. - example: null - revoked_at: - format: date-time - type: - - string - - 'null' - description: >- - The timestamp when the invitation was revoked, - or null if not revoked. - example: null - expires_at: - format: date-time - type: string - description: The timestamp when the invitation expires. - example: '2026-01-15T12:00:00.000Z' - organization_id: - type: - - string - - 'null' - description: >- - The ID of the - [organization](/reference/organization) that the - recipient will join. - example: org_01E4ZCR3C56J083X43JQXF3JK5 - inviter_user_id: - type: - - string - - 'null' - description: >- - The ID of the user who invited the recipient, if - provided. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - accepted_user_id: - type: - - string - - 'null' - description: >- - The ID of the user who accepted the invitation, - once accepted. - example: null - 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' - token: - type: string - description: The token used to accept the invitation. - example: Z1uX3RbwcIl5fIGJJJCXXisdI - accept_invitation_url: - type: string - description: >- - The URL where the recipient can accept the - invitation. - example: >- - https://your-app.com/invite?invitation_token=Z1uX3RbwcIl5fIGJJJCXXisdI - required: - - object - - id - - email - - state - - accepted_at - - revoked_at - - expires_at - - organization_id - - inviter_user_id - - accepted_user_id - - created_at - - updated_at - - token - - accept_invitation_url + $ref: '#/components/schemas/UserlandUserInvite' '422': description: Unprocessable Entity content: @@ -16606,108 +10757,7 @@ paths: content: application/json: schema: - type: object - properties: - object: - type: string - description: Distinguishes the invitation object. - const: invitation - id: - type: string - description: The unique ID of the invitation. - example: invitation_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: string - description: The email address of the recipient. - example: marcelina.davis@example.com - state: - type: string - enum: - - pending - - accepted - - expired - - revoked - description: The state of the invitation. - example: pending - accepted_at: - format: date-time - type: - - string - - 'null' - description: >- - The timestamp when the invitation was accepted, or null if - not yet accepted. - example: null - revoked_at: - format: date-time - type: - - string - - 'null' - description: >- - The timestamp when the invitation was revoked, or null if - not revoked. - example: null - expires_at: - format: date-time - type: string - description: The timestamp when the invitation expires. - example: '2026-01-15T12:00:00.000Z' - organization_id: - type: - - string - - 'null' - description: >- - The ID of the [organization](/reference/organization) that - the recipient will join. - example: org_01E4ZCR3C56J083X43JQXF3JK5 - inviter_user_id: - type: - - string - - 'null' - description: The ID of the user who invited the recipient, if provided. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - accepted_user_id: - type: - - string - - 'null' - description: >- - The ID of the user who accepted the invitation, once - accepted. - example: null - 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' - token: - type: string - description: The token used to accept the invitation. - example: Z1uX3RbwcIl5fIGJJJCXXisdI - accept_invitation_url: - type: string - description: The URL where the recipient can accept the invitation. - example: >- - https://your-app.com/invite?invitation_token=Z1uX3RbwcIl5fIGJJJCXXisdI - required: - - object - - id - - email - - state - - accepted_at - - revoked_at - - expires_at - - organization_id - - inviter_user_id - - accepted_user_id - - created_at - - updated_at - - token - - accept_invitation_url + $ref: '#/components/schemas/UserlandUserInvite' '400': description: Bad Request content: @@ -16863,111 +10913,45 @@ paths: responses: '200': description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/UserlandUserInvite' + '404': + description: Not Found content: application/json: schema: type: object properties: - object: - type: string - description: Distinguishes the invitation object. - const: invitation - id: - type: string - description: The unique ID of the invitation. - example: invitation_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: string - description: The email address of the recipient. - example: marcelina.davis@example.com - state: + message: type: string - enum: - - pending - - accepted - - expired - - revoked - description: The state of the invitation. - example: pending - accepted_at: - format: date-time - type: - - string - - 'null' - description: >- - The timestamp when the invitation was accepted, or null if - not yet accepted. - example: null - revoked_at: - format: date-time - type: - - string - - 'null' - description: >- - The timestamp when the invitation was revoked, or null if - not revoked. - example: null - expires_at: - format: date-time - type: string - description: The timestamp when the invitation expires. - example: '2026-01-15T12:00:00.000Z' - organization_id: - type: - - string - - 'null' - description: >- - The ID of the [organization](/reference/organization) that - the recipient will join. - example: org_01E4ZCR3C56J083X43JQXF3JK5 - inviter_user_id: - type: - - string - - 'null' - description: The ID of the user who invited the recipient, if provided. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - accepted_user_id: - type: - - string - - 'null' - description: >- - The ID of the user who accepted the invitation, once - accepted. - example: null - 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' - token: - type: string - description: The token used to accept the invitation. - example: Z1uX3RbwcIl5fIGJJJCXXisdI - accept_invitation_url: - type: string - description: The URL where the recipient can accept the invitation. - example: >- - https://your-app.com/invite?invitation_token=Z1uX3RbwcIl5fIGJJJCXXisdI + description: A human-readable description of the error. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - - object - - id - - email - - state - - accepted_at - - revoked_at - - expires_at - - organization_id - - inviter_user_id - - accepted_user_id - - created_at - - updated_at - - token - - accept_invitation_url + - message + tags: + - user-management.invitations + /user_management/invitations/{id}: + get: + operationId: UserlandUserInvitesController_get + summary: Get an invitation + description: Get the details of an existing invitation. + parameters: + - name: id + required: true + in: path + description: The unique ID of the invitation. + schema: + example: invitation_01E4ZCR3C56J083X43JQXF3JK5 + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/UserlandUserInvite' '404': description: Not Found content: @@ -16983,11 +10967,13 @@ paths: - message tags: - user-management.invitations - /user_management/invitations/{id}: - get: - operationId: UserlandUserInvitesController_get - summary: Get an invitation - description: Get the details of an existing invitation. + /user_management/invitations/{id}/accept: + post: + operationId: UserlandUserInvitesController_accept + summary: Accept an invitation + description: >- + Accepts an invitation and, if linked to an organization, activates the + user's membership in that organization. parameters: - name: id required: true @@ -17024,7 +11010,7 @@ paths: - expired - revoked description: The state of the invitation. - example: pending + example: accepted accepted_at: format: date-time type: @@ -17033,7 +11019,7 @@ paths: description: >- The timestamp when the invitation was accepted, or null if not yet accepted. - example: null + example: '2026-01-15T12:00:00.000Z' revoked_at: format: date-time type: @@ -17061,7 +11047,7 @@ paths: - string - 'null' description: The ID of the user who invited the recipient, if provided. - example: user_01E4ZCR3C56J083X43JQXF3JK5 + example: user_01HYGBX8ZGD19949T3BM4FW1C3 accepted_user_id: type: - string @@ -17069,7 +11055,7 @@ paths: description: >- The ID of the user who accepted the invitation, once accepted. - example: null + example: user_01E4ZCR3C56J083X43JQXF3JK5 created_at: format: date-time type: string @@ -17104,6 +11090,27 @@ paths: - updated_at - token - accept_invitation_url + x-inline-with-overrides: true + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + code: + type: string + enum: + - invite_not_pending + - invalid_invite + - invite_has_accepted_user_id + message: + type: string + description: A human-readable description of the error. + example: Invite is not pending. + required: + - code + - message '404': description: Not Found content: @@ -17119,13 +11126,116 @@ paths: - message tags: - user-management.invitations - /user_management/invitations/{id}/accept: + /user_management/invitations/{id}/resend: post: - operationId: UserlandUserInvitesController_accept - summary: Accept an invitation + operationId: UserlandUserInvitesController_resend + summary: Resend an invitation description: >- - Accepts an invitation and, if linked to an organization, activates the - user's membership in that organization. + Resends an invitation email to the recipient. The invitation must be in + a pending state. + parameters: + - name: id + required: true + in: path + description: The unique ID of the invitation. + schema: + example: invitation_01E4ZCR3C56J083X43JQXF3JK5 + type: string + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ResendUserlandUserInviteOptionsDto' + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/UserlandUserInvite' + '400': + description: Bad Request + content: + application/json: + schema: + oneOf: + - type: object + properties: + code: + type: string + const: invite_expired + message: + type: string + description: A human-readable description of the error. + example: Invite has expired. + required: + - code + - message + - type: object + properties: + code: + type: string + const: invite_revoked + message: + type: string + description: A human-readable description of the error. + example: Invite has been revoked. + required: + - code + - message + - type: object + properties: + code: + type: string + const: invite_accepted + message: + type: string + description: A human-readable description of the error. + example: Invite has already been accepted. + 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 + '422': + description: Unprocessable Entity + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_request_parameters + const: invalid_request_parameters + message: + type: string + description: A human-readable description of the error. + example: Validation failed. + required: + - code + - message + tags: + - user-management.invitations + x-sends-email: true + /user_management/invitations/{id}/revoke: + post: + operationId: UserlandUserInvitesController_revoke + summary: Revoke an invitation + description: Revokes an existing invitation. parameters: - name: id required: true @@ -17162,7 +11272,7 @@ paths: - expired - revoked description: The state of the invitation. - example: accepted + example: revoked accepted_at: format: date-time type: @@ -17171,7 +11281,7 @@ paths: description: >- The timestamp when the invitation was accepted, or null if not yet accepted. - example: '2026-01-15T12:00:00.000Z' + example: null revoked_at: format: date-time type: @@ -17180,7 +11290,7 @@ paths: description: >- The timestamp when the invitation was revoked, or null if not revoked. - example: null + example: '2026-01-15T12:00:00.000Z' expires_at: format: date-time type: string @@ -17199,7 +11309,7 @@ paths: - string - 'null' description: The ID of the user who invited the recipient, if provided. - example: user_01E4ZCR3C56J083X43JQXF3JK5 + example: user_01HYGBX8ZGD19949T3BM4FW1C3 accepted_user_id: type: - string @@ -17207,7 +11317,7 @@ paths: description: >- The ID of the user who accepted the invitation, once accepted. - example: user_01E4ZCR3C56J083X43JQXF3JK5 + example: null created_at: format: date-time type: string @@ -17242,6 +11352,7 @@ paths: - updated_at - token - accept_invitation_url + x-inline-with-overrides: true '400': description: Bad Request content: @@ -17251,10 +11362,9 @@ paths: properties: code: type: string - enum: - - invite_not_pending - - invalid_invite - - invite_has_accepted_user_id + description: The error code identifying the type of error. + example: invite_not_pending + const: invite_not_pending message: type: string description: A human-readable description of the error. @@ -17262,150 +11372,71 @@ paths: required: - code - message - '404': - description: Not Found + tags: + - user-management.invitations + /user_management/jwt_template: + put: + operationId: JwtTemplatesController_updateJwtTemplate + summary: Update JWT template + description: Update the JWT template for the current environment. + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateJwtTemplateDto' + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/JwtTemplateResponse' + '422': + description: Unprocessable Entity content: application/json: schema: type: object properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_request_parameters + const: invalid_request_parameters message: type: string description: A human-readable description of the error. - example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + example: Validation failed. required: + - code - message tags: - - user-management.invitations - /user_management/invitations/{id}/resend: + - user-management.jwt-template + /user_management/magic_auth: post: - operationId: UserlandUserInvitesController_resend - summary: Resend an invitation + operationId: UserlandMagicAuthController_sendMagicAuthCodeAndReturn + summary: Create a Magic Auth code description: >- - Resends an invitation email to the recipient. The invitation must be in - a pending state. - parameters: - - name: id - required: true - in: path - description: The unique ID of the invitation. - schema: - example: invitation_01E4ZCR3C56J083X43JQXF3JK5 - type: string + Creates a one-time authentication code that can be sent to the user's + email address. The code expires in 10 minutes. To verify the code, + [authenticate the user with Magic + Auth](/reference/authkit/authentication/magic-auth). + parameters: [] requestBody: required: true content: application/json: schema: - $ref: '#/components/schemas/ResendUserlandUserInviteOptionsDto' + $ref: '#/components/schemas/CreateUserlandMagicCodeAndReturnDto' responses: - '200': - description: OK + '201': + description: Created content: application/json: schema: - type: object - properties: - object: - type: string - description: Distinguishes the invitation object. - const: invitation - id: - type: string - description: The unique ID of the invitation. - example: invitation_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: string - description: The email address of the recipient. - example: marcelina.davis@example.com - state: - type: string - enum: - - pending - - accepted - - expired - - revoked - description: The state of the invitation. - example: pending - accepted_at: - format: date-time - type: - - string - - 'null' - description: >- - The timestamp when the invitation was accepted, or null if - not yet accepted. - example: null - revoked_at: - format: date-time - type: - - string - - 'null' - description: >- - The timestamp when the invitation was revoked, or null if - not revoked. - example: null - expires_at: - format: date-time - type: string - description: The timestamp when the invitation expires. - example: '2026-01-15T12:00:00.000Z' - organization_id: - type: - - string - - 'null' - description: >- - The ID of the [organization](/reference/organization) that - the recipient will join. - example: org_01E4ZCR3C56J083X43JQXF3JK5 - inviter_user_id: - type: - - string - - 'null' - description: The ID of the user who invited the recipient, if provided. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - accepted_user_id: - type: - - string - - 'null' - description: >- - The ID of the user who accepted the invitation, once - accepted. - example: null - 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' - token: - type: string - description: The token used to accept the invitation. - example: Z1uX3RbwcIl5fIGJJJCXXisdI - accept_invitation_url: - type: string - description: The URL where the recipient can accept the invitation. - example: >- - https://your-app.com/invite?invitation_token=Z1uX3RbwcIl5fIGJJJCXXisdI - required: - - object - - id - - email - - state - - accepted_at - - revoked_at - - expires_at - - organization_id - - inviter_user_id - - accepted_user_id - - created_at - - updated_at - - token - - accept_invitation_url + $ref: '#/components/schemas/MagicAuth' '400': description: Bad Request content: @@ -17414,42 +11445,50 @@ paths: oneOf: - type: object properties: - code: + error: type: string - const: invite_expired - message: + description: The OAuth error code. + example: invitation_invalid + const: invitation_invalid + error_description: type: string description: A human-readable description of the error. - example: Invite has expired. + example: 'The request failed due to: invitation_invalid.' required: - - code - - message + - error + - error_description - type: object properties: - code: + error: type: string - const: invite_revoked - message: + description: The OAuth error code. + example: authentication_method_not_allowed + const: authentication_method_not_allowed + error_description: type: string description: A human-readable description of the error. - example: Invite has been revoked. + example: >- + The request failed due to: + authentication_method_not_allowed. required: - - code - - message + - error + - error_description - type: object properties: - code: + error: type: string - const: invite_accepted - message: + description: The OAuth error code. + example: sign_up_not_allowed + const: sign_up_not_allowed + error_description: type: string description: A human-readable description of the error. - example: Invite has already been accepted. + example: 'The request failed due to: sign_up_not_allowed.' required: - - code - - message - '404': - description: Not Found + - error + - error_description + '422': + description: Unprocessable Entity content: application/json: schema: @@ -17461,8 +11500,8 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - '422': - description: Unprocessable Entity + '429': + description: '' content: application/json: schema: @@ -17471,290 +11510,200 @@ paths: code: type: string description: The error code identifying the type of error. - example: invalid_request_parameters - const: invalid_request_parameters + example: daily_quota_exceeded + const: daily_quota_exceeded message: type: string description: A human-readable description of the error. - example: Validation failed. + example: Request could not be processed. required: - code - message tags: - - user-management.invitations + - user-management.magic-auth x-sends-email: true - /user_management/invitations/{id}/revoke: - post: - operationId: UserlandUserInvitesController_revoke - summary: Revoke an invitation - description: Revokes an existing invitation. + /user_management/magic_auth/{id}: + get: + operationId: UserlandMagicAuthController_get + summary: Get Magic Auth code details + description: >- + Get the details of an existing [Magic + Auth](/reference/authkit/magic-auth) code that can be used to send an + email to a user for authentication. parameters: - name: id required: true in: path - description: The unique ID of the invitation. + description: The unique ID of the Magic Auth code. schema: - example: invitation_01E4ZCR3C56J083X43JQXF3JK5 + example: magic_auth_01HWZBQZY2M3AMQW166Q22K88F type: string responses: '200': description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/MagicAuth' + '404': + description: Not Found content: application/json: schema: type: object properties: - object: - type: string - description: Distinguishes the invitation object. - const: invitation - id: - type: string - description: The unique ID of the invitation. - example: invitation_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: string - description: The email address of the recipient. - example: marcelina.davis@example.com - state: - type: string - enum: - - pending - - accepted - - expired - - revoked - description: The state of the invitation. - example: revoked - accepted_at: - format: date-time - type: - - string - - 'null' - description: >- - The timestamp when the invitation was accepted, or null if - not yet accepted. - example: null - revoked_at: - format: date-time - type: - - string - - 'null' - description: >- - The timestamp when the invitation was revoked, or null if - not revoked. - example: '2026-01-15T12:00:00.000Z' - expires_at: - format: date-time - type: string - description: The timestamp when the invitation expires. - example: '2026-01-15T12:00:00.000Z' - organization_id: - type: - - string - - 'null' - description: >- - The ID of the [organization](/reference/organization) that - the recipient will join. - example: org_01E4ZCR3C56J083X43JQXF3JK5 - inviter_user_id: - type: - - string - - 'null' - description: The ID of the user who invited the recipient, if provided. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - accepted_user_id: - type: - - string - - 'null' - description: >- - The ID of the user who accepted the invitation, once - accepted. - example: null - 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' - token: - type: string - description: The token used to accept the invitation. - example: Z1uX3RbwcIl5fIGJJJCXXisdI - accept_invitation_url: - type: string - description: The URL where the recipient can accept the invitation. - example: >- - https://your-app.com/invite?invitation_token=Z1uX3RbwcIl5fIGJJJCXXisdI - required: - - object - - id - - email - - state - - accepted_at - - revoked_at - - expires_at - - organization_id - - inviter_user_id - - accepted_user_id - - created_at - - updated_at - - token - - accept_invitation_url - '400': - description: Bad Request - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invite_not_pending - const: invite_not_pending - message: + message: type: string description: A human-readable description of the error. - example: Invite is not pending. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - - code - message tags: - - user-management.invitations - /user_management/jwt_template: - put: - operationId: JwtTemplatesController_updateJwtTemplate - summary: Update JWT template - description: Update the JWT template for the current environment. - parameters: [] - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/UpdateJwtTemplateDto' + - user-management.magic-auth + /user_management/organization_memberships: + get: + operationId: UserlandUserOrganizationMembershipsController_list + summary: List organization memberships + description: >- + Get a list of all organization memberships matching the criteria + specified. At least one of `user_id` or `organization_id` must be + provided. By default only active memberships are returned. Use the + `statuses` parameter to filter by other statuses. + 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: number + - 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: + default: desc + example: desc + enum: + - normal + - desc + - asc + type: string + - name: organization_id + required: false + in: query + description: >- + The ID of the [organization](/reference/organization) which the user + belongs to. + schema: + example: org_01E4ZCR3C56J083X43JQXF3JK5 + type: string + - name: statuses + required: false + in: query + description: >- + Filter by the status of the organization membership. Array including + any of `active`, `inactive`, or `pending`. + style: form + explode: false + schema: + example: + - active + type: array + items: + type: string + enum: + - active + - inactive + - pending + - name: user_id + required: false + in: query + description: The ID of the [user](/reference/authkit/user). + schema: + example: user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E + type: string responses: '200': description: OK content: application/json: schema: - type: object - properties: - object: - type: string - description: The object type. - const: jwt_template - content: - type: string - description: The JWT template content as a Liquid template string. - example: '{"iss": "{{environment.id}}", "sub": "{{user.id}}"}' - created_at: - type: string - description: The timestamp when the JWT template was created. - example: '2026-01-15T12:00:00.000Z' - updated_at: - type: string - description: The timestamp when the JWT template was last updated. - example: '2026-01-15T12:00:00.000Z' - required: - - object - - content - - created_at - - updated_at - '422': - description: Unprocessable Entity - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_request_parameters - const: invalid_request_parameters - message: - type: string - description: A human-readable description of the error. - example: Validation failed. - required: - - code - - message - tags: - - user-management.jwt-template - /user_management/magic_auth: - post: - operationId: UserlandMagicAuthController_sendMagicAuthCodeAndReturn - summary: Create a Magic Auth code - description: >- - Creates a one-time authentication code that can be sent to the user's - email address. The code expires in 10 minutes. To verify the code, - [authenticate the user with Magic - Auth](/reference/authkit/authentication/magic-auth). - parameters: [] - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreateUserlandMagicCodeAndReturnDto' - responses: - '201': - description: Created - content: - application/json: - schema: - type: object - properties: - object: - type: string - description: Distinguishes the Magic Auth object. - const: magic_auth - id: - type: string - description: The unique ID of the Magic Auth code. - example: magic_auth_01HWZBQZY2M3AMQW166Q22K88F - user_id: - type: string - description: The unique ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: string - description: The email address of the user. - example: marcelina.davis@example.com - expires_at: - format: date-time - type: string - description: The timestamp when the Magic Auth code expires. - example: '2026-01-15T12:00:00.000Z' - 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' - code: - type: string - description: The code used to verify the Magic Auth code. - example: '123456' - required: - - object - - id - - user_id - - email - - expires_at - - created_at - - updated_at - - code + allOf: + - type: object + properties: + object: + type: string + description: Indicates this is a list response. + const: list + 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: om_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: om_01HXYZ987654321KJIHGFEDCBA + required: + - before + - after + description: >- + Pagination cursors for navigating between pages of + results. + - type: object + properties: + data: + type: array + description: The list of records for the current page. + items: + $ref: >- + #/components/schemas/UserlandUserOrganizationMembership '400': description: Bad Request content: @@ -17763,50 +11712,34 @@ paths: oneOf: - type: object properties: - error: - type: string - description: The OAuth error code. - example: invitation_invalid - const: invitation_invalid - error_description: - type: string - description: A human-readable description of the error. - example: 'The request failed due to: invitation_invalid.' - required: - - error - - error_description - - type: object - properties: - error: + code: type: string - description: The OAuth error code. - example: authentication_method_not_allowed - const: authentication_method_not_allowed - error_description: + description: The error code identifying the type of error. + example: invalid_request_parameters + const: invalid_request_parameters + message: type: string description: A human-readable description of the error. - example: >- - The request failed due to: - authentication_method_not_allowed. + example: Validation failed. required: - - error - - error_description + - code + - message - type: object properties: - error: + code: type: string - description: The OAuth error code. - example: sign_up_not_allowed - const: sign_up_not_allowed - error_description: + description: The error code identifying the type of error. + example: missing_user_id_or_organization_id + const: missing_user_id_or_organization_id + message: type: string description: A human-readable description of the error. - example: 'The request failed due to: sign_up_not_allowed.' + example: Request could not be processed. required: - - error - - error_description - '422': - description: Unprocessable Entity + - code + - message + '404': + description: Not Found content: application/json: schema: @@ -17818,47 +11751,42 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - '429': - description: '' + '422': + description: Unprocessable Entity content: application/json: schema: type: object properties: - code: - type: string - description: The error code identifying the type of error. - example: daily_quota_exceeded - const: daily_quota_exceeded message: type: string description: A human-readable description of the error. - example: Request could not be processed. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - - code - message tags: - - user-management.magic-auth - x-sends-email: true - /user_management/magic_auth/{id}: - get: - operationId: UserlandMagicAuthController_get - summary: Get Magic Auth code details + - user-management.organization-membership + post: + operationId: UserlandUserOrganizationMembershipsController_create + summary: Create an organization membership description: >- - Get the details of an existing [Magic - Auth](/reference/authkit/magic-auth) code that can be used to send an - email to a user for authentication. - parameters: - - name: id - required: true - in: path - description: The unique ID of the Magic Auth code. - schema: - example: magic_auth_01HWZBQZY2M3AMQW166Q22K88F - type: string + Creates a new `active` organization membership for the given + organization and user. + + + Calling this API with an organization and user that match an `inactive` + organization membership will activate the membership with the specified + role(s). + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateUserlandUserOrganizationMembershipDto' responses: - '200': - description: OK + '201': + description: Created content: application/json: schema: @@ -17866,25 +11794,53 @@ paths: properties: object: type: string - description: Distinguishes the Magic Auth object. - const: magic_auth + description: Distinguishes the organization membership object. + const: organization_membership id: type: string - description: The unique ID of the Magic Auth code. - example: magic_auth_01HWZBQZY2M3AMQW166Q22K88F + description: The unique ID of the organization membership. + example: om_01HXYZ123456789ABCDEFGHIJ user_id: type: string - description: The unique ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - email: + description: The ID of the user. + example: user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E + organization_id: type: string - description: The email address of the user. - example: marcelina.davis@example.com - expires_at: - format: date-time + description: The ID of the organization which the user belongs to. + example: org_01E4ZCR3C56J083X43JQXF3JK5 + status: type: string - description: The timestamp when the Magic Auth code expires. - example: '2026-01-15T12:00:00.000Z' + enum: + - active + - inactive + - pending + description: >- + The status of the organization membership. One of + `active`, `inactive`, or `pending`. + example: active + directory_managed: + type: boolean + description: >- + Whether this organization membership is managed by a + directory sync connection. + example: false + organization_name: + type: string + description: The name of the organization which the user belongs to. + example: Acme Corp + custom_attributes: + type: object + additionalProperties: {} + description: >- + An object containing IdP-sourced attributes from the + linked [Directory + User](/reference/directory-sync/directory-user) or [SSO + Profile](/reference/sso/profile). Directory User + attributes take precedence when both are linked. + example: + department: Engineering + title: Developer Experience Engineer + location: Brooklyn created_at: format: date-time type: string @@ -17895,18 +11851,42 @@ paths: type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' - code: - type: string - description: The code used to verify the Magic Auth code. - example: '123456' + role: + $ref: '#/components/schemas/SlimRole' + description: >- + The primary role assigned to the user within the + organization. required: - object - id - user_id - - email - - expires_at + - organization_id + - status + - directory_managed - created_at - updated_at + - role + x-inline-with-overrides: true + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + message: + type: string + description: A human-readable description of the error. + example: >- + A pending organization membership cannot be reactivated. + The user needs to accept the invitation instead. + code: + type: string + description: The error code identifying the type of error. + example: cannot_reactivate_pending_organization_membership + const: cannot_reactivate_pending_organization_membership + required: + - message - code '404': description: Not Found @@ -17921,242 +11901,8 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - tags: - - user-management.magic-auth - /user_management/organization_memberships: - get: - operationId: UserlandUserOrganizationMembershipsController_list - summary: List organization memberships - description: >- - Get a list of all organization memberships matching the criteria - specified. At least one of `user_id` or `organization_id` must be - provided. By default only active memberships are returned. Use the - `statuses` parameter to filter by other statuses. - 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: number - - 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: - default: desc - example: desc - enum: - - normal - - desc - - asc - type: string - - name: organization_id - required: false - in: query - description: >- - The ID of the [organization](/reference/organization) which the user - belongs to. - schema: - example: org_01E4ZCR3C56J083X43JQXF3JK5 - type: string - - name: statuses - required: false - in: query - description: >- - Filter by the status of the organization membership. Array including - any of `active`, `inactive`, or `pending`. - style: form - explode: false - schema: - example: - - active - type: array - items: - type: string - enum: - - active - - inactive - - pending - - name: user_id - required: false - in: query - description: The ID of the [user](/reference/authkit/user). - schema: - example: user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - allOf: - - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - 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: om_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: om_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: >- - Pagination cursors for navigating between pages of - results. - - type: object - properties: - data: - type: array - description: The list of records for the current page. - items: - type: object - properties: - object: - type: string - description: >- - Distinguishes the organization membership - object. - const: organization_membership - id: - type: string - description: The unique ID of the organization membership. - example: om_01HXYZ123456789ABCDEFGHIJ - user_id: - type: string - description: The ID of the user. - example: user_01EHQTV6MWP9P1F4ZXGXMC8ABB - organization_id: - type: string - description: >- - The ID of the organization which the user - belongs to. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - status: - type: string - enum: - - active - - inactive - - pending - description: >- - The status of the organization membership. One - of `active`, `inactive`, or `pending`. - example: active - directory_managed: - type: boolean - description: >- - Whether this organization membership is managed - by a directory sync connection. - example: false - organization_name: - type: string - description: >- - The name of the organization which the user - belongs to. - example: Acme Corp - custom_attributes: - type: object - additionalProperties: {} - description: >- - An object containing IdP-sourced attributes from - the linked [Directory - User](/reference/directory-sync/directory-user) - or [SSO Profile](/reference/sso/profile). - Directory User attributes take precedence when - both are linked. - example: - department: Engineering - title: Developer Experience Engineer - location: Brooklyn - 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' - role: - type: object - properties: - slug: - type: string - description: The slug of the assigned role. - example: admin - required: - - slug - description: >- - The primary role assigned to the user within the - organization. - required: - - object - - id - - user_id - - organization_id - - status - - directory_managed - - created_at - - updated_at - - role - '400': - description: Bad Request + '422': + description: Unprocessable Entity content: application/json: schema: @@ -18177,35 +11923,79 @@ paths: - message - type: object properties: + message: + type: string + description: A human-readable description of the error. + example: Role 'invalid_slug' is not a valid role. code: type: string description: The error code identifying the type of error. - example: missing_user_id_or_organization_id - const: missing_user_id_or_organization_id + example: invalid_role + const: invalid_role + required: + - message + - code + - type: object + properties: message: type: string description: A human-readable description of the error. - example: Request could not be processed. + example: Multiple roles are not enabled for this environment. + code: + type: string + description: The error code identifying the type of error. + example: multiple_roles_not_enabled + const: multiple_roles_not_enabled 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 - '422': - description: Unprocessable Entity - content: - application/json: + - code + - type: object + properties: + message: + type: string + description: A human-readable description of the error. + example: >- + Sub-resource scoped roles are not allowed for this + operation. + code: + type: string + description: The error code identifying the type of error. + example: sub_resource_scoped_role_not_allowed + const: sub_resource_scoped_role_not_allowed + role_slug: + type: string + description: The slug of the role that is not allowed. + example: admin + required: + - message + - code + - role_slug + tags: + - user-management.organization-membership + /user_management/organization_memberships/{id}: + get: + operationId: UserlandUserOrganizationMembershipsController_get + summary: Get an organization membership + description: Get the details of an existing organization membership. + parameters: + - name: id + required: true + in: path + description: The unique ID of the organization membership. + schema: + example: om_01HXYZ123456789ABCDEFGHIJ + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/UserlandUserOrganizationMembership' + '404': + description: Not Found + content: + application/json: schema: type: object properties: @@ -18217,115 +12007,25 @@ paths: - message tags: - user-management.organization-membership - post: - operationId: UserlandUserOrganizationMembershipsController_create - summary: Create an organization membership + delete: + operationId: UserlandUserOrganizationMembershipsController_delete + summary: Delete an organization membership description: >- - Creates a new `active` organization membership for the given - organization and user. - - - Calling this API with an organization and user that match an `inactive` - organization membership will activate the membership with the specified - role(s). - parameters: [] - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreateUserlandUserOrganizationMembershipDto' + Permanently deletes an existing organization membership. It cannot be + undone. + parameters: + - name: id + required: true + in: path + description: The unique ID of the organization membership. + schema: + example: om_01HXYZ123456789ABCDEFGHIJ + type: string responses: - '201': - description: Created - content: - application/json: - schema: - type: object - properties: - object: - type: string - description: Distinguishes the organization membership object. - const: organization_membership - id: - type: string - description: The unique ID of the organization membership. - example: om_01HXYZ123456789ABCDEFGHIJ - user_id: - type: string - description: The ID of the user. - example: user_01EHQTV6MWP9P1F4ZXGXMC8ABB - organization_id: - type: string - description: The ID of the organization which the user belongs to. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - status: - type: string - enum: - - active - - inactive - - pending - description: >- - The status of the organization membership. One of - `active`, `inactive`, or `pending`. - example: active - directory_managed: - type: boolean - description: >- - Whether this organization membership is managed by a - directory sync connection. - example: false - organization_name: - type: string - description: The name of the organization which the user belongs to. - example: Acme Corp - custom_attributes: - type: object - additionalProperties: {} - description: >- - An object containing IdP-sourced attributes from the - linked [Directory - User](/reference/directory-sync/directory-user) or [SSO - Profile](/reference/sso/profile). Directory User - attributes take precedence when both are linked. - example: - department: Engineering - title: Developer Experience Engineer - location: Brooklyn - 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' - role: - type: object - properties: - slug: - type: string - description: The slug of the assigned role. - example: admin - required: - - slug - description: >- - The primary role assigned to the user within the - organization. - required: - - object - - id - - user_id - - organization_id - - status - - directory_managed - - created_at - - updated_at - - role - '400': - description: Bad Request + '200': + description: OK + '404': + description: Not Found content: application/json: schema: @@ -18334,17 +12034,36 @@ paths: message: type: string description: A human-readable description of the error. - example: >- - A pending organization membership cannot be reactivated. - The user needs to accept the invitation instead. - code: - type: string - description: The error code identifying the type of error. - example: cannot_reactivate_pending_organization_membership - const: cannot_reactivate_pending_organization_membership + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - - code + tags: + - user-management.organization-membership + put: + operationId: UserlandUserOrganizationMembershipsController_update + summary: Update an organization membership + description: Update the details of an existing organization membership. + parameters: + - name: id + required: true + in: path + description: The unique ID of the organization membership. + schema: + example: om_01HXYZ123456789ABCDEFGHIJ + type: string + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateUserlandUserOrganizationMembershipDto' + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/UserlandUserOrganizationMembership' '404': description: Not Found content: @@ -18429,11 +12148,27 @@ paths: - role_slug tags: - user-management.organization-membership - /user_management/organization_memberships/{id}: - get: - operationId: UserlandUserOrganizationMembershipsController_get - summary: Get an organization membership - description: Get the details of an existing organization membership. + /user_management/organization_memberships/{id}/deactivate: + put: + operationId: UserlandUserOrganizationMembershipsController_deactivate + summary: Deactivate an organization membership + description: >- + Deactivates an `active` organization membership. Emits an + [organization_membership.updated](/events/organization-membership) event + upon successful deactivation. + + + - Deactivating an `inactive` membership is a no-op and does not emit an + event. + + - Deactivating a `pending` membership returns an error. This membership + should be [deleted](/reference/authkit/organization-membership/delete) + instead. + + + See the [membership management + documentation](/authkit/users-organizations/organizations/membership-management) + for additional details. parameters: - name: id required: true @@ -18475,7 +12210,7 @@ paths: description: >- The status of the organization membership. One of `active`, `inactive`, or `pending`. - example: active + example: inactive directory_managed: type: boolean description: >- @@ -18510,14 +12245,7 @@ paths: description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' role: - type: object - properties: - slug: - type: string - description: The slug of the assigned role. - example: admin - required: - - slug + $ref: '#/components/schemas/SlimRole' description: >- The primary role assigned to the user within the organization. @@ -18531,8 +12259,9 @@ paths: - created_at - updated_at - role - '404': - description: Not Found + x-inline-with-overrides: true + '400': + description: Bad Request content: application/json: schema: @@ -18541,28 +12270,17 @@ paths: message: type: string description: A human-readable description of the error. - example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + example: >- + A pending organization membership cannot be deactivated. + This membership should be deleted instead. + code: + type: string + description: The error code identifying the type of error. + example: cannot_deactivate_pending_organization_membership + const: cannot_deactivate_pending_organization_membership required: - message - tags: - - user-management.organization-membership - delete: - operationId: UserlandUserOrganizationMembershipsController_delete - summary: Delete an organization membership - description: >- - Permanently deletes an existing organization membership. It cannot be - undone. - parameters: - - name: id - required: true - in: path - description: The unique ID of the organization membership. - schema: - example: om_01HXYZ123456789ABCDEFGHIJ - type: string - responses: - '200': - description: OK + - code '404': description: Not Found content: @@ -18576,12 +12294,48 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message + '422': + description: Unprocessable Entity + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_request_parameters + const: invalid_request_parameters + message: + type: string + description: A human-readable description of the error. + example: Validation failed. + required: + - code + - message tags: - user-management.organization-membership + /user_management/organization_memberships/{id}/reactivate: put: - operationId: UserlandUserOrganizationMembershipsController_update - summary: Update an organization membership - description: Update the details of an existing organization membership. + operationId: UserlandUserOrganizationMembershipsController_reactivate + summary: Reactivate an organization membership + description: >- + Reactivates an `inactive` organization membership, retaining the + pre-existing role(s). Emits an + [organization_membership.updated](/events/organization-membership) event + upon successful reactivation. + + + - Reactivating an `active` membership is a no-op and does not emit an + event. + + - Reactivating a `pending` membership returns an error. The user needs + to [accept the invitation](/authkit/invitations) instead. + + + See the [membership management + documentation](/authkit/users-organizations/organizations/membership-management) + for additional details. parameters: - name: id required: true @@ -18590,101 +12344,34 @@ paths: schema: example: om_01HXYZ123456789ABCDEFGHIJ type: string - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/UpdateUserlandUserOrganizationMembershipDto' responses: '200': description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/UserlandUserOrganizationMembership' + '400': + description: Bad Request content: application/json: schema: type: object properties: - object: - type: string - description: Distinguishes the organization membership object. - const: organization_membership - id: - type: string - description: The unique ID of the organization membership. - example: om_01HXYZ123456789ABCDEFGHIJ - user_id: - type: string - description: The ID of the user. - example: user_01EHQTV6MWP9P1F4ZXGXMC8ABB - organization_id: - type: string - description: The ID of the organization which the user belongs to. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - status: - type: string - enum: - - active - - inactive - - pending - description: >- - The status of the organization membership. One of - `active`, `inactive`, or `pending`. - example: active - directory_managed: - type: boolean - description: >- - Whether this organization membership is managed by a - directory sync connection. - example: false - organization_name: - type: string - description: The name of the organization which the user belongs to. - example: Acme Corp - custom_attributes: - type: object - additionalProperties: {} - description: >- - An object containing IdP-sourced attributes from the - linked [Directory - User](/reference/directory-sync/directory-user) or [SSO - Profile](/reference/sso/profile). Directory User - attributes take precedence when both are linked. - example: - department: Engineering - title: Developer Experience Engineer - location: Brooklyn - created_at: - format: date-time + message: type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - updated_at: - format: date-time + description: A human-readable description of the error. + example: >- + A pending organization membership cannot be reactivated. + The user needs to accept the invitation instead. + code: type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - role: - type: object - properties: - slug: - type: string - description: The slug of the assigned role. - example: admin - required: - - slug - description: >- - The primary role assigned to the user within the - organization. + description: The error code identifying the type of error. + example: cannot_reactivate_pending_organization_membership + const: cannot_reactivate_pending_organization_membership required: - - object - - id - - user_id - - organization_id - - status - - directory_managed - - created_at - - updated_at - - role + - message + - code '404': description: Not Found content: @@ -18700,6 +12387,46 @@ paths: - message '422': description: Unprocessable Entity + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_request_parameters + const: invalid_request_parameters + message: + type: string + description: A human-readable description of the error. + example: Validation failed. + required: + - code + - message + tags: + - user-management.organization-membership + /user_management/password_reset: + post: + operationId: UserlandUsersController_createPasswordResetToken + summary: Create a password reset token + description: Creates a one-time token that can be used to reset a user's password. + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreatePasswordResetTokenDto' + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/PasswordReset' + '403': + description: Forbidden content: application/json: schema: @@ -18709,184 +12436,105 @@ paths: code: type: string description: The error code identifying the type of error. - example: invalid_request_parameters - const: invalid_request_parameters + example: email_password_auth_disabled + const: email_password_auth_disabled message: type: string description: A human-readable description of the error. - example: Validation failed. + example: Request could not be processed. required: - code - message - type: object properties: - message: - type: string - description: A human-readable description of the error. - example: Role 'invalid_slug' is not a valid role. code: type: string description: The error code identifying the type of error. - example: invalid_role - const: invalid_role - required: - - message - - code - - type: object - properties: + example: password_reset_not_allowed + const: password_reset_not_allowed message: type: string description: A human-readable description of the error. - example: Multiple roles are not enabled for this environment. - code: - type: string - description: The error code identifying the type of error. - example: multiple_roles_not_enabled - const: multiple_roles_not_enabled + example: Request could not be processed. required: - - message - code - - type: object - properties: - message: - type: string - description: A human-readable description of the error. - example: >- - Sub-resource scoped roles are not allowed for this - operation. - code: - type: string - description: The error code identifying the type of error. - example: sub_resource_scoped_role_not_allowed - const: sub_resource_scoped_role_not_allowed - role_slug: - type: string - description: The slug of the role that is not allowed. - example: admin - required: - message - - code - - role_slug - tags: - - user-management.organization-membership - /user_management/organization_memberships/{id}/deactivate: - put: - operationId: UserlandUserOrganizationMembershipsController_deactivate - summary: Deactivate an organization membership - description: >- - Deactivates an `active` organization membership. Emits an - [organization_membership.updated](/events/organization-membership) event - upon successful deactivation. - - - - Deactivating an `inactive` membership is a no-op and does not emit an - event. - - - Deactivating a `pending` membership returns an error. This membership - should be [deleted](/reference/authkit/organization-membership/delete) - instead. - - - See the [membership management - documentation](/authkit/users-organizations/organizations/membership-management) - for additional details. - parameters: - - name: id - required: true - in: path - description: The unique ID of the organization membership. - schema: - example: om_01HXYZ123456789ABCDEFGHIJ - type: string - responses: - '200': - description: OK + '404': + description: Not Found content: application/json: schema: type: object properties: - object: - type: string - description: Distinguishes the organization membership object. - const: organization_membership - id: - type: string - description: The unique ID of the organization membership. - example: om_01HXYZ123456789ABCDEFGHIJ - user_id: - type: string - description: The ID of the user. - example: user_01EHQTV6MWP9P1F4ZXGXMC8ABB - organization_id: + message: type: string - description: The ID of the organization which the user belongs to. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - status: + 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: + code: type: string - enum: - - active - - inactive - - pending - description: >- - The status of the organization membership. One of - `active`, `inactive`, or `pending`. - example: inactive - directory_managed: - type: boolean - description: >- - Whether this organization membership is managed by a - directory sync connection. - example: false - organization_name: + description: The error code identifying the type of error. + example: invalid_request_parameters + const: invalid_request_parameters + message: type: string - description: The name of the organization which the user belongs to. - example: Acme Corp - custom_attributes: - type: object - additionalProperties: {} - description: >- - An object containing IdP-sourced attributes from the - linked [Directory - User](/reference/directory-sync/directory-user) or [SSO - Profile](/reference/sso/profile). Directory User - attributes take precedence when both are linked. - example: - department: Engineering - title: Developer Experience Engineer - location: Brooklyn - created_at: - format: date-time + description: A human-readable description of the error. + example: Validation failed. + required: + - code + - message + '429': + description: '' + content: + application/json: + schema: + type: object + properties: + code: type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - updated_at: - format: date-time + description: The error code identifying the type of error. + example: daily_quota_exceeded + const: daily_quota_exceeded + message: type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - role: - type: object - properties: - slug: - type: string - description: The slug of the assigned role. - example: admin - required: - - slug - description: >- - The primary role assigned to the user within the - organization. + description: A human-readable description of the error. + example: Request could not be processed. required: - - object - - id - - user_id - - organization_id - - status - - directory_managed - - created_at - - updated_at - - role + - code + - message + tags: + - user-management.users + x-sends-email: true + /user_management/password_reset/confirm: + post: + operationId: UserlandUsersController_resetPassword + summary: Reset the password + description: >- + Sets a new password using the `token` query parameter from the link that + the user received. Successfully resetting the password will verify a + user's email, if it hasn't been verified yet. + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreatePasswordResetDto' + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ResetPasswordResponse' '400': description: Bad Request content: @@ -18894,20 +12542,57 @@ paths: schema: type: object properties: + code: + type: string + description: The error code identifying the type of error. + example: password_reset_error + const: password_reset_error message: type: string description: A human-readable description of the error. - example: >- - A pending organization membership cannot be deactivated. - This membership should be deleted instead. + example: Validation failed. + errors: + type: array + items: + type: object + properties: + code: + type: string + description: The validation error code. + example: unknown_event_type + message: + type: string + description: >- + A human-readable description of the validation + error. + example: Invalid enum value. + required: + - code + - message + description: The list of validation errors. + required: + - code + - message + - errors + '403': + description: Forbidden + content: + application/json: + schema: + type: object + properties: code: type: string description: The error code identifying the type of error. - example: cannot_deactivate_pending_organization_membership - const: cannot_deactivate_pending_organization_membership + example: email_password_auth_disabled + const: email_password_auth_disabled + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. required: - - message - code + - message '404': description: Not Found content: @@ -18941,125 +12626,70 @@ paths: - code - message tags: - - user-management.organization-membership - /user_management/organization_memberships/{id}/reactivate: - put: - operationId: UserlandUserOrganizationMembershipsController_reactivate - summary: Reactivate an organization membership + - user-management.users + /user_management/password_reset/{id}: + get: + operationId: UserlandUsersController_getPasswordReset + summary: Get a password reset token description: >- - Reactivates an `inactive` organization membership, retaining the - pre-existing role(s). Emits an - [organization_membership.updated](/events/organization-membership) event - upon successful reactivation. - - - - Reactivating an `active` membership is a no-op and does not emit an - event. - - - Reactivating a `pending` membership returns an error. The user needs - to [accept the invitation](/authkit/invitations) instead. - - - See the [membership management - documentation](/authkit/users-organizations/organizations/membership-management) - for additional details. + Get the details of an existing password reset token that can be used to + reset a user's password. parameters: - name: id required: true in: path - description: The unique ID of the organization membership. + description: The ID of the password reset token. schema: - example: om_01HXYZ123456789ABCDEFGHIJ type: string + example: password_reset_01E4ZCR3C56J083X43JQXF3JK5 responses: '200': description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/PasswordReset' + '404': + description: Not Found content: application/json: schema: type: object properties: - object: - type: string - description: Distinguishes the organization membership object. - const: organization_membership - id: - type: string - description: The unique ID of the organization membership. - example: om_01HXYZ123456789ABCDEFGHIJ - user_id: - type: string - description: The ID of the user. - example: user_01EHQTV6MWP9P1F4ZXGXMC8ABB - organization_id: + message: type: string - description: The ID of the organization which the user belongs to. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - status: - type: string - enum: - - active - - inactive - - pending - description: >- - The status of the organization membership. One of - `active`, `inactive`, or `pending`. - example: active - directory_managed: - type: boolean - description: >- - Whether this organization membership is managed by a - directory sync connection. - example: false - organization_name: - type: string - description: The name of the organization which the user belongs to. - example: Acme Corp - custom_attributes: - type: object - additionalProperties: {} - description: >- - An object containing IdP-sourced attributes from the - linked [Directory - User](/reference/directory-sync/directory-user) or [SSO - Profile](/reference/sso/profile). Directory User - attributes take precedence when both are linked. - example: - department: Engineering - title: Developer Experience Engineer - location: Brooklyn - 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' - role: - type: object - properties: - slug: - type: string - description: The slug of the assigned role. - example: admin - required: - - slug - description: >- - The primary role assigned to the user within the - organization. + description: A human-readable description of the error. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - - object - - id - - user_id - - organization_id - - status - - directory_managed - - created_at - - updated_at - - role + - message + tags: + - user-management.users + /user_management/redirect_uris: + post: + operationId: RedirectUrisController_create + summary: Create a redirect URI + description: Creates a new redirect URI for an environment. + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateRedirectUriDto' + responses: + '201': + description: Redirect URI created successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/RedirectUri' + example: + object: redirect_uri + id: ruri_01EHZNVPK3SFK441A1RGBFSHRT + uri: https://example.com/callback + default: true + created_at: '2026-01-15T12:00:00.000Z' + updated_at: '2026-01-15T12:00:00.000Z' '400': description: Bad Request content: @@ -19070,19 +12700,28 @@ paths: message: type: string description: A human-readable description of the error. - example: >- - A pending organization membership cannot be reactivated. - The user needs to accept the invitation instead. - code: + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + required: + - message + example: + message: Bad Request + '401': + description: Unauthorized + content: + application/json: + schema: + type: object + properties: + message: type: string - description: The error code identifying the type of error. - example: cannot_reactivate_pending_organization_membership - const: cannot_reactivate_pending_organization_membership + description: A human-readable description of the error. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - - code - '404': - description: Not Found + example: + message: Unauthorized + '422': + description: Validation failed. content: application/json: schema: @@ -19094,6 +12733,48 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message + example: + message: Redirect URI 'https://example.com/callback' already exists. + tags: + - user-management.redirect-uris + /user_management/sessions/logout: + get: + operationId: UserlandSessionsController_logout + summary: Logout + security: [] + description: Logout a user from the current [session](/reference/authkit/session). + parameters: + - name: session_id + required: true + in: query + description: >- + The ID of the session to revoke. This can be extracted from the + `sid` claim of the access token. + schema: + example: session_01H93ZY4F80QPBEZ1R5B2SHQG8 + type: string + - name: return_to + required: false + in: query + description: The URL to redirect the user to after session revocation. + schema: + example: https://example.com + type: string + responses: + '200': + headers: + location: + schema: + type: string + format: uri + description: OK + '302': + headers: + location: + schema: + type: string + format: uri + description: '' '422': description: Unprocessable Entity content: @@ -19101,347 +12782,298 @@ paths: schema: type: object properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_request_parameters - const: invalid_request_parameters message: type: string description: A human-readable description of the error. - example: Validation failed. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - - code - message tags: - - user-management.organization-membership - /user_management/password_reset: + - user-management.authentication + /user_management/sessions/revoke: post: - operationId: UserlandUsersController_createPasswordResetToken - summary: Create a password reset token - description: Creates a one-time token that can be used to reset a user's password. + operationId: UserlandSessionsController_revokeSession + summary: Revoke Session + description: Revoke a [user session](/reference/authkit/session). parameters: [] requestBody: required: true content: application/json: schema: - $ref: '#/components/schemas/CreatePasswordResetTokenDto' + $ref: '#/components/schemas/UserlandRevokeSessionDto' responses: - '201': - description: Created + '200': + description: OK + '400': + description: Bad Request content: application/json: schema: type: object properties: - object: - type: string - description: Distinguishes the password reset object. - const: password_reset - id: - type: string - description: The unique ID of the password reset object. - example: password_reset_01E4ZCR3C56J083X43JQXF3JK5 - user_id: - type: string - description: The unique ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: string - description: The email address of the user. - example: marcelina.davis@example.com - expires_at: - format: date-time - type: string - description: The timestamp when the password reset token expires. - example: '2026-01-15T12:00:00.000Z' - created_at: - format: date-time - type: string - description: The timestamp when the password reset token was created. - example: '2026-01-15T12:00:00.000Z' - password_reset_token: - type: string - description: The token used to reset the password. - example: Z1uX3RbwcIl5fIGJJJCXXisdI - password_reset_url: + message: type: string - description: The URL where the user can reset their password. - example: >- - https://your-app.com/reset-password?token=Z1uX3RbwcIl5fIGJJJCXXisdI - required: - - object - - id - - user_id - - email - - expires_at - - created_at - - password_reset_token - - password_reset_url - '403': - description: Forbidden - content: - application/json: - schema: - oneOf: - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: email_password_auth_disabled - const: email_password_auth_disabled - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: password_reset_not_allowed - const: password_reset_not_allowed - 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''.' + description: A human-readable description of the error. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - '422': - description: Unprocessable Entity + tags: + - user-management.authentication + /user_management/users: + get: + operationId: UserlandUsersController_list + summary: List users + description: >- + Get a list of all of your existing users matching the criteria + specified. + 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: number + - 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: + default: desc + example: desc + enum: + - normal + - desc + - asc + type: string + - name: organization + required: false + in: query + deprecated: true + description: >- + Filter users by the organization they are a member of. Deprecated in + favor of `organization_id`. + schema: + example: org_01EHZNVPK3SFK441A1RGBFSHRT + type: string + - name: organization_id + required: false + in: query + description: Filter users by the organization they are a member of. + schema: + example: org_01EHZNVPK3SFK441A1RGBFSHRT + type: string + - name: email + required: false + in: query + description: Filter users by their email address. + schema: + example: user@example.com + type: string + responses: + '200': + description: OK content: application/json: schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_request_parameters - const: invalid_request_parameters - message: - type: string - description: A human-readable description of the error. - example: Validation failed. - required: - - code - - message - '429': - description: '' + $ref: '#/components/schemas/UserlandUserList' + '422': + description: Unprocessable Entity content: application/json: schema: type: object properties: - code: - type: string - description: The error code identifying the type of error. - example: daily_quota_exceeded - const: daily_quota_exceeded message: type: string description: A human-readable description of the error. - example: Request could not be processed. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - - code - message tags: - user-management.users - x-sends-email: true - /user_management/password_reset/confirm: post: - operationId: UserlandUsersController_resetPassword - summary: Reset the password - description: >- - Sets a new password using the `token` query parameter from the link that - the user received. Successfully resetting the password will verify a - user's email, if it hasn't been verified yet. + operationId: UserlandUsersController_create + summary: Create a user + description: Create a new user in the current environment. parameters: [] requestBody: required: true content: application/json: schema: - $ref: '#/components/schemas/CreatePasswordResetDto' + $ref: '#/components/schemas/CreateUserlandUserDto' responses: - '200': - description: OK + '201': + description: Created content: application/json: schema: - type: object - properties: - user: - type: object + $ref: '#/components/schemas/UserlandUser' + '400': + description: Bad Request + content: + application/json: + schema: + oneOf: + - type: object properties: - object: + code: type: string - description: Distinguishes the user object. - const: user - id: + description: The error code identifying the type of error. + example: password_strength_error + const: password_strength_error + message: type: string - description: The unique ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - first_name: - type: - - string - - 'null' - description: The first name of the user. - example: Marcelina - last_name: - type: - - string - - 'null' - description: The last name of the user. - example: Davis - profile_picture_url: - type: - - string - - 'null' - description: A URL reference to an image representing the user. - example: https://workoscdn.com/images/v1/123abc - email: + description: A human-readable description of the error. + example: Validation failed. + errors: + type: array + items: + type: object + properties: + code: + type: string + description: The validation error code. + example: unknown_event_type + message: + type: string + description: >- + A human-readable description of the validation + error. + example: Invalid enum value. + required: + - code + - message + description: The list of validation errors. + required: + - code + - message + - errors + - type: object + properties: + code: type: string - description: The email address of the user. - example: marcelina.davis@example.com - email_verified: - type: boolean - description: Whether the user's email has been verified. - example: true - external_id: - type: - - string - - 'null' - description: The external ID of the user. - example: f1ffa2b2-c20b-4d39-be5c-212726e11222 - metadata: - type: object - additionalProperties: - type: string - maxLength: 600 - description: >- - Object containing metadata key/value pairs associated - with the user. - example: - timezone: America/New_York - propertyNames: - maxLength: 40 - maxProperties: 50 - last_sign_in_at: - format: date-time - type: - - string - - 'null' - description: The timestamp when the user last signed in. - example: '2025-06-25T19:07:33.155Z' - locale: - type: - - string - - 'null' - description: The user's preferred locale. - example: en-US - created_at: - format: date-time + description: The error code identifying the type of error. + example: user_creation_error + const: user_creation_error + message: type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - updated_at: - format: date-time + description: A human-readable description of the error. + example: Validation failed. + errors: + type: array + items: + type: object + properties: + code: + type: string + description: The validation error code. + example: unknown_event_type + message: + type: string + description: >- + A human-readable description of the validation + error. + example: Invalid enum value. + required: + - code + - message + description: The list of validation errors. + required: + - code + - message + - errors + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_password_hash + const: invalid_password_hash + message: type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' + description: A human-readable description of the error. + example: Request could not be processed. required: - - object - - id - - first_name - - last_name - - profile_picture_url - - email - - email_verified - - external_id - - last_sign_in_at - - created_at - - updated_at - description: The user whose password was reset. - required: - - user - '400': - description: Bad Request - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: password_reset_error - const: password_reset_error - message: - type: string - description: A human-readable description of the error. - example: Validation failed. - errors: - type: array - items: - type: object - properties: - code: - type: string - description: The validation error code. - example: unknown_event_type - message: - type: string - description: >- - A human-readable description of the validation - error. - example: Invalid enum value. - required: - - code - - message - description: The list of validation errors. - required: - - code - - message - - errors - '403': - description: Forbidden - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: email_password_auth_disabled - const: email_password_auth_disabled - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: password_and_password_hash_provided + const: password_and_password_hash_provided + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: password_and_password_hash_type_provided + const: password_and_password_hash_type_provided + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_metadata + const: invalid_metadata + 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: @@ -19476,73 +13108,28 @@ paths: - message tags: - user-management.users - /user_management/password_reset/{id}: + /user_management/users/external_id/{external_id}: get: - operationId: UserlandUsersController_getPasswordReset - summary: Get a password reset token + operationId: UserlandUsersController_getByExternalId + summary: Get a user by external ID description: >- - Get the details of an existing password reset token that can be used to - reset a user's password. + Get the details of an existing user by an [external + identifier](/authkit/metadata/external-identifiers). parameters: - - name: id + - name: external_id required: true in: path - description: The ID of the password reset token. + description: The external ID of the user. schema: + example: f1ffa2b2-c20b-4d39-be5c-212726e11222 type: string - example: password_reset_01E4ZCR3C56J083X43JQXF3JK5 responses: '200': description: OK content: application/json: schema: - type: object - properties: - object: - type: string - description: Distinguishes the password reset object. - const: password_reset - id: - type: string - description: The unique ID of the password reset object. - example: password_reset_01E4ZCR3C56J083X43JQXF3JK5 - user_id: - type: string - description: The unique ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: string - description: The email address of the user. - example: marcelina.davis@example.com - expires_at: - format: date-time - type: string - description: The timestamp when the password reset token expires. - example: '2026-01-15T12:00:00.000Z' - created_at: - format: date-time - type: string - description: The timestamp when the password reset token was created. - example: '2026-01-15T12:00:00.000Z' - password_reset_token: - type: string - description: The token used to reset the password. - example: Z1uX3RbwcIl5fIGJJJCXXisdI - password_reset_url: - type: string - description: The URL where the user can reset their password. - example: >- - https://your-app.com/reset-password?token=Z1uX3RbwcIl5fIGJJJCXXisdI - required: - - object - - id - - user_id - - email - - expires_at - - created_at - - password_reset_token - - password_reset_url + $ref: '#/components/schemas/UserlandUser' '404': description: Not Found content: @@ -19558,149 +13145,214 @@ paths: - message tags: - user-management.users - /user_management/redirect_uris: - post: - operationId: RedirectUrisController_create - summary: Create a redirect URI - description: Creates a new redirect URI for an environment. - parameters: [] + /user_management/users/{id}: + put: + operationId: UserlandUsersController_update + summary: Update a user + description: >- + Updates properties of a user. The omitted properties will be left + unchanged. + parameters: + - name: id + required: true + in: path + description: The unique ID of the user. + schema: + example: user_01E4ZCR3C56J083X43JQXF3JK5 + type: string requestBody: required: true content: application/json: schema: - $ref: '#/components/schemas/CreateRedirectUriDto' + $ref: '#/components/schemas/UpdateUserlandUserDto' responses: - '201': - description: Redirect URI created successfully. + '200': + description: OK content: application/json: schema: - type: object - properties: - object: - type: string - description: The object type. - const: redirect_uri - id: - type: string - description: The ID of the redirect URI. - example: ruri_01EHZNVPK3SFK441A1RGBFSHRT - uri: - type: string - description: The redirect URI. - example: https://example.com/callback - default: - type: boolean - description: Whether this is the default redirect URI. - example: true - created_at: - type: string - description: The timestamp when the redirect URI was created. - example: '2026-01-15T12:00:00.000Z' - updated_at: - type: string - description: The timestamp when the redirect URI was last updated. - example: '2026-01-15T12:00:00.000Z' - required: - - object - - id - - uri - - default - - created_at - - updated_at - example: - object: redirect_uri - id: ruri_01EHZNVPK3SFK441A1RGBFSHRT - uri: https://example.com/callback - default: true - created_at: '2026-01-15T12:00:00.000Z' - updated_at: '2026-01-15T12:00:00.000Z' + $ref: '#/components/schemas/UserlandUser' '400': description: Bad Request 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 - example: - message: Bad Request - '401': - description: Unauthorized - 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 - example: - message: Unauthorized - '422': - description: Validation failed. - 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 - example: - message: Redirect URI 'https://example.com/callback' already exists. - tags: - - user-management.redirect-uris - /user_management/sessions/logout: - get: - operationId: UserlandSessionsController_logout - summary: Logout - security: [] - description: Logout a user from the current [session](/reference/authkit/session). - parameters: - - name: session_id - required: true - in: query - description: >- - The ID of the session to revoke. This can be extracted from the - `sid` claim of the access token. - schema: - example: session_01H93ZY4F80QPBEZ1R5B2SHQG8 - type: string - - name: return_to - required: false - in: query - description: The URL to redirect the user to after session revocation. - schema: - example: https://example.com - type: string - responses: - '200': - headers: - location: - schema: - type: string - format: uri - description: OK - '302': - headers: - location: - schema: - type: string - format: uri - description: '' + oneOf: + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: password_strength_error + const: password_strength_error + message: + type: string + description: A human-readable description of the error. + example: Validation failed. + errors: + type: array + items: + type: object + properties: + code: + type: string + description: The validation error code. + example: unknown_event_type + message: + type: string + description: >- + A human-readable description of the validation + error. + example: Invalid enum value. + required: + - code + - message + description: The list of validation errors. + required: + - code + - message + - errors + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_password_hash + const: invalid_password_hash + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: password_and_password_hash_provided + const: password_and_password_hash_provided + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: password_and_password_hash_type_provided + const: password_and_password_hash_type_provided + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: email_already_verified + const: email_already_verified + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_metadata + const: invalid_metadata + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: external_id_already_used + const: external_id_already_used + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: email_change_not_allowed + const: email_change_not_allowed + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: email_not_available + const: email_not_available + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_email + const: invalid_email + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_locale + const: invalid_locale + 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: @@ -19708,31 +13360,41 @@ paths: schema: type: object properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_request_parameters + const: invalid_request_parameters message: type: string description: A human-readable description of the error. - example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + example: Validation failed. required: + - code - message tags: - - user-management.authentication - /user_management/sessions/revoke: - post: - operationId: UserlandSessionsController_revokeSession - summary: Revoke Session - description: Revoke a [user session](/reference/authkit/session). - parameters: [] - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/UserlandRevokeSessionDto' + - user-management.users + get: + operationId: UserlandUsersController_get + summary: Get a user + description: Get the details of an existing user. + parameters: + - name: id + required: true + in: path + description: The unique ID of the user. + schema: + example: user_01E4ZCR3C56J083X43JQXF3JK5 + type: string responses: '200': description: OK - '400': - description: Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/UserlandUser' + '404': + description: Not Found content: application/json: schema: @@ -19745,229 +13407,26 @@ paths: required: - message tags: - - user-management.authentication - /user_management/users: - get: - operationId: UserlandUsersController_list - summary: List users + - user-management.users + delete: + operationId: UserlandUsersController_delete + summary: Delete a user description: >- - Get a list of all of your existing users matching the criteria - specified. + Permanently deletes a user in the current environment. It cannot be + undone. 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: number - - 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: - default: desc - example: desc - enum: - - normal - - desc - - asc - type: string - - name: organization - required: false - in: query - deprecated: true - description: >- - Filter users by the organization they are a member of. Deprecated in - favor of `organization_id`. - schema: - example: org_01EHZNVPK3SFK441A1RGBFSHRT - type: string - - name: organization_id - required: false - in: query - description: Filter users by the organization they are a member of. - schema: - example: org_01EHZNVPK3SFK441A1RGBFSHRT - type: string - - name: email - required: false - in: query - description: Filter users by their email address. + - name: id + required: true + in: path + description: The unique ID of the user. schema: - example: user@example.com + example: user_01E4ZCR3C56J083X43JQXF3JK5 type: string responses: '200': description: OK - content: - application/json: - schema: - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - type: object - properties: - object: - type: string - description: Distinguishes the user object. - const: user - id: - type: string - description: The unique ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - first_name: - type: - - string - - 'null' - description: The first name of the user. - example: Marcelina - last_name: - type: - - string - - 'null' - description: The last name of the user. - example: Davis - profile_picture_url: - type: - - string - - 'null' - description: A URL reference to an image representing the user. - example: https://workoscdn.com/images/v1/123abc - email: - type: string - description: The email address of the user. - example: marcelina.davis@example.com - email_verified: - type: boolean - description: Whether the user's email has been verified. - example: true - external_id: - type: - - string - - 'null' - description: The external ID of the user. - example: f1ffa2b2-c20b-4d39-be5c-212726e11222 - metadata: - type: object - additionalProperties: - type: string - maxLength: 600 - description: >- - Object containing metadata key/value pairs - associated with the user. - example: - timezone: America/New_York - propertyNames: - maxLength: 40 - maxProperties: 50 - last_sign_in_at: - format: date-time - type: - - string - - 'null' - description: The timestamp when the user last signed in. - example: '2025-06-25T19:07:33.155Z' - locale: - type: - - string - - 'null' - description: The user's preferred locale. - example: en-US - 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 - - first_name - - last_name - - profile_picture_url - - email - - email_verified - - external_id - - last_sign_in_at - - created_at - - updated_at - 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: user_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: user_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: >- - Pagination cursors for navigating between pages of - results. - required: - - object - - data - - list_metadata - '422': - description: Unprocessable Entity + '404': + description: Not Found content: application/json: schema: @@ -19981,113 +13440,32 @@ paths: - message tags: - user-management.users + /user_management/users/{id}/email_verification/confirm: post: - operationId: UserlandUsersController_create - summary: Create a user - description: Create a new user in the current environment. - parameters: [] + operationId: UserlandUsersController_emailVerification + summary: Verify email + description: Verifies an email address using the one-time code received by the user. + parameters: + - name: id + required: true + in: path + description: The ID of the user. + schema: + type: string + example: user_01E4ZCR3C56J083X43JQXF3JK5 requestBody: required: true content: application/json: schema: - $ref: '#/components/schemas/CreateUserlandUserDto' + $ref: '#/components/schemas/VerifyEmailAddressDto' responses: - '201': - description: Created + '200': + description: OK content: application/json: schema: - type: object - properties: - object: - type: string - description: Distinguishes the user object. - const: user - id: - type: string - description: The unique ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - first_name: - type: - - string - - 'null' - description: The first name of the user. - example: Marcelina - last_name: - type: - - string - - 'null' - description: The last name of the user. - example: Davis - profile_picture_url: - type: - - string - - 'null' - description: A URL reference to an image representing the user. - example: https://workoscdn.com/images/v1/123abc - email: - type: string - description: The email address of the user. - example: marcelina.davis@example.com - email_verified: - type: boolean - description: Whether the user's email has been verified. - example: true - external_id: - type: - - string - - 'null' - description: The external ID of the user. - example: f1ffa2b2-c20b-4d39-be5c-212726e11222 - metadata: - type: object - additionalProperties: - type: string - maxLength: 600 - description: >- - Object containing metadata key/value pairs associated with - the user. - example: - timezone: America/New_York - propertyNames: - maxLength: 40 - maxProperties: 50 - last_sign_in_at: - format: date-time - type: - - string - - 'null' - description: The timestamp when the user last signed in. - example: '2025-06-25T19:07:33.155Z' - locale: - type: - - string - - 'null' - description: The user's preferred locale. - example: en-US - 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 - - first_name - - last_name - - profile_picture_url - - email - - email_verified - - external_id - - last_sign_in_at - - created_at - - updated_at + $ref: '#/components/schemas/VerifyEmailResponse' '400': description: Bad Request content: @@ -20099,90 +13477,22 @@ paths: code: type: string description: The error code identifying the type of error. - example: password_strength_error - const: password_strength_error + example: email_previously_verified + const: email_previously_verified message: type: string description: A human-readable description of the error. - example: Validation failed. - errors: - type: array - items: - type: object - properties: - code: - type: string - description: The validation error code. - example: unknown_event_type - message: - type: string - description: >- - A human-readable description of the validation - error. - example: Invalid enum value. - required: - - code - - message - description: The list of validation errors. + example: Request could not be processed. required: - code - message - - errors - type: object properties: code: type: string description: The error code identifying the type of error. - example: user_creation_error - const: user_creation_error - message: - type: string - description: A human-readable description of the error. - example: Validation failed. - errors: - type: array - items: - type: object - properties: - code: - type: string - description: The validation error code. - example: unknown_event_type - message: - type: string - description: >- - A human-readable description of the validation - error. - example: Invalid enum value. - required: - - code - - message - description: The list of validation errors. - required: - - code - - message - - errors - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_password_hash - const: invalid_password_hash - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: password_and_password_hash_provided - const: password_and_password_hash_provided + example: email_verification_code_previously_used + const: email_verification_code_previously_used message: type: string description: A human-readable description of the error. @@ -20195,8 +13505,8 @@ paths: code: type: string description: The error code identifying the type of error. - example: password_and_password_hash_type_provided - const: password_and_password_hash_type_provided + example: email_verification_code_expired + const: email_verification_code_expired message: type: string description: A human-readable description of the error. @@ -20209,8 +13519,8 @@ paths: code: type: string description: The error code identifying the type of error. - example: invalid_metadata - const: invalid_metadata + example: email_verification_code_incorrect + const: email_verification_code_incorrect message: type: string description: A human-readable description of the error. @@ -20252,117 +13562,47 @@ paths: - message tags: - user-management.users - /user_management/users/external_id/{external_id}: - get: - operationId: UserlandUsersController_getByExternalId - summary: Get a user by external ID + /user_management/users/{id}/email_verification/send: + post: + operationId: UserlandUsersController_sendVerificationEmail + summary: Send verification email description: >- - Get the details of an existing user by an [external - identifier](/authkit/metadata/external-identifiers). + Sends an email that contains a one-time code used to verify a user’s + email address. parameters: - - name: external_id + - name: id required: true in: path - description: The external ID of the user. + description: The ID of the user. schema: - example: f1ffa2b2-c20b-4d39-be5c-212726e11222 type: string + example: user_01E4ZCR3C56J083X43JQXF3JK5 responses: '200': description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/SendVerificationEmailResponse' + '400': + description: Bad Request content: application/json: schema: type: object properties: - object: - type: string - description: Distinguishes the user object. - const: user - id: - type: string - description: The unique ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - first_name: - type: - - string - - 'null' - description: The first name of the user. - example: Marcelina - last_name: - type: - - string - - 'null' - description: The last name of the user. - example: Davis - profile_picture_url: - type: - - string - - 'null' - description: A URL reference to an image representing the user. - example: https://workoscdn.com/images/v1/123abc - email: - type: string - description: The email address of the user. - example: marcelina.davis@example.com - email_verified: - type: boolean - description: Whether the user's email has been verified. - example: true - external_id: - type: - - string - - 'null' - description: The external ID of the user. - example: f1ffa2b2-c20b-4d39-be5c-212726e11222 - metadata: - type: object - additionalProperties: - type: string - maxLength: 600 - description: >- - Object containing metadata key/value pairs associated with - the user. - example: - timezone: America/New_York - propertyNames: - maxLength: 40 - maxProperties: 50 - last_sign_in_at: - format: date-time - type: - - string - - 'null' - description: The timestamp when the user last signed in. - example: '2025-06-25T19:07:33.155Z' - locale: - type: - - string - - 'null' - description: The user's preferred locale. - example: en-US - created_at: - format: date-time + code: type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - updated_at: - format: date-time + description: The error code identifying the type of error. + example: email_already_verified + const: email_already_verified + message: type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' + description: A human-readable description of the error. + example: Request could not be processed. required: - - object - - id - - first_name - - last_name - - profile_picture_url - - email - - email_verified - - external_id - - last_sign_in_at - - created_at - - updated_at + - code + - message '404': description: Not Found content: @@ -20376,15 +13616,36 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message + '429': + description: '' + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: daily_quota_exceeded + const: daily_quota_exceeded + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message tags: - user-management.users - /user_management/users/{id}: - put: - operationId: UserlandUsersController_update - summary: Update a user + /user_management/users/{id}/identities: + get: + operationId: UserlandUserIdentitiesController_get + summary: Get user identities description: >- - Updates properties of a user. The omitted properties will be left - unchanged. + Get a list of identities associated with the user. A user can have + multiple associated identities after going through [identity + linking](/authkit/identity-linking). Currently only OAuth identities are + supported. More provider types may be added in the future. parameters: - name: id required: true @@ -20393,288 +13654,310 @@ paths: schema: example: user_01E4ZCR3C56J083X43JQXF3JK5 type: string - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/UpdateUserlandUserDto' responses: '200': description: OK + content: + application/json: + schema: + type: array + items: + type: object + properties: + idp_id: + type: string + description: >- + The unique ID of the user in the external identity + provider. + example: 4F42ABDE-1E44-4B66-824A-5F733C037A6D + type: + type: string + description: The type of the identity. + const: OAuth + provider: + type: string + enum: + - AppleOAuth + - BitbucketOAuth + - DiscordOAuth + - GithubOAuth + - GitLabOAuth + - GoogleOAuth + - IntuitOAuth + - LinkedInOAuth + - MicrosoftOAuth + - SalesforceOAuth + - SlackOAuth + - VercelMarketplaceOAuth + - VercelOAuth + - XeroOAuth + description: The type of OAuth provider for the identity. + example: MicrosoftOAuth + required: + - idp_id + - type + - provider + '404': + description: Not Found content: application/json: schema: type: object properties: - object: - type: string - description: Distinguishes the user object. - const: user - id: - type: string - description: The unique ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - first_name: - type: - - string - - 'null' - description: The first name of the user. - example: Marcelina - last_name: - type: - - string - - 'null' - description: The last name of the user. - example: Davis - profile_picture_url: - type: - - string - - 'null' - description: A URL reference to an image representing the user. - example: https://workoscdn.com/images/v1/123abc - email: + message: type: string - description: The email address of the user. - example: marcelina.davis@example.com - email_verified: - type: boolean - description: Whether the user's email has been verified. - example: true - external_id: - type: - - string - - 'null' - description: The external ID of the user. - example: f1ffa2b2-c20b-4d39-be5c-212726e11222 - metadata: - type: object - additionalProperties: - type: string - maxLength: 600 - description: >- - Object containing metadata key/value pairs associated with - the user. - example: - timezone: America/New_York - propertyNames: - maxLength: 40 - maxProperties: 50 - last_sign_in_at: - format: date-time - type: - - string - - 'null' - description: The timestamp when the user last signed in. - example: '2025-06-25T19:07:33.155Z' - locale: - type: - - string - - 'null' - description: The user's preferred locale. - example: en-US - 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' + description: A human-readable description of the error. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - - object - - id - - first_name - - last_name - - profile_picture_url - - email - - email_verified - - external_id - - last_sign_in_at - - created_at - - updated_at - '400': - description: Bad Request + - message + tags: + - user-management.users + /user_management/users/{id}/sessions: + get: + operationId: UserlandUserSessionsController_list + summary: List sessions + description: Get a list of all active sessions for a specific user. + parameters: + - name: id + required: true + in: path + description: The ID of the user. + schema: + type: string + example: user_01EHZNVPK3SFK441A1RGBFSHRT + - 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: number + - 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: + default: desc + example: desc + enum: + - normal + - desc + - asc + type: string + responses: + '200': + description: OK content: application/json: schema: - oneOf: + allOf: - type: object properties: - code: - type: string - description: The error code identifying the type of error. - example: password_strength_error - const: password_strength_error - message: + object: type: string - description: A human-readable description of the error. - example: Validation failed. - errors: + description: Indicates this is a list response. + const: list + 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: session_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: session_01HXYZ987654321KJIHGFEDCBA + required: + - before + - after + description: >- + Pagination cursors for navigating between pages of + results. + - type: object + properties: + data: type: array + description: The list of records for the current page. items: type: object properties: - code: + object: type: string - description: The validation error code. - example: unknown_event_type - message: + description: Distinguishes the session object. + const: session + id: + type: string + description: The unique ID of the session. + example: session_01H93ZY4F80QPBEZ1R5B2SHQG8 + impersonator: + type: object + properties: + email: + type: string + description: >- + The email address of the WorkOS Dashboard + user who is impersonating the user. + example: admin@foocorp.com + reason: + type: + - string + - 'null' + description: >- + The justification the impersonator gave for + impersonating the user. + example: >- + Investigating an issue with the customer's + account. + required: + - email + - reason + description: >- + Information about the impersonator if this + session was created via impersonation. + ip_address: + type: + - string + - 'null' + description: >- + The IP address from which the session was + created. + example: 198.51.100.42 + organization_id: type: string description: >- - A human-readable description of the validation - error. - example: Invalid enum value. + The ID of the organization this session is + associated with. + example: org_01H945H0YD4F97JN9MATX7BYAG + user_agent: + type: + - string + - 'null' + description: >- + The user agent string from the device that + created the session. + example: >- + Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) + AppleWebKit/537.36 + user_id: + type: string + description: The ID of the user this session belongs to. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + auth_method: + type: string + enum: + - cross_app_auth + - external_auth + - impersonation + - magic_code + - migrated_session + - oauth + - passkey + - password + - sso + - unknown + description: >- + The authentication method used to create this + session. + example: sso + status: + type: string + enum: + - active + - expired + - revoked + description: The current status of the session. + example: active + expires_at: + format: date-time + type: string + description: The timestamp when the session expires. + example: '2026-01-15T12:00:00.000Z' + ended_at: + format: date-time + type: + - string + - 'null' + description: The timestamp when the session ended. + example: null + 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: - - code - - message - description: The list of validation errors. - required: - - code - - message - - errors - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_password_hash - const: invalid_password_hash - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: password_and_password_hash_provided - const: password_and_password_hash_provided - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: password_and_password_hash_type_provided - const: password_and_password_hash_type_provided - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: email_already_verified - const: email_already_verified - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_metadata - const: invalid_metadata - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: external_id_already_used - const: external_id_already_used - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: email_change_not_allowed - const: email_change_not_allowed - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: email_not_available - const: email_not_available - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_email - const: invalid_email - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_locale - const: invalid_locale - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message + - object + - id + - ip_address + - user_agent + - user_id + - auth_method + - status + - expires_at + - ended_at + - created_at + - updated_at + '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: @@ -20696,114 +13979,158 @@ paths: - message tags: - user-management.users + /user_management/users/{userId}/feature-flags: get: - operationId: UserlandUsersController_get - summary: Get a user - description: Get the details of an existing user. + operationId: UserlandUserFeatureFlagsController_list + summary: List enabled feature flags for a user + description: >- + Get a list of all enabled feature flags for the provided user. This + includes feature flags enabled specifically for the user as well as any + organizations that the user is a member of. parameters: - - name: id + - name: userId required: true in: path - description: The unique ID of the user. + description: The ID of the user. schema: example: user_01E4ZCR3C56J083X43JQXF3JK5 type: string + - 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. + schema: + example: obj_1234567890 + 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. + schema: + example: obj_1234567890 + 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: number + - name: order + required: false + in: query + description: Order the results by the creation time. + schema: + default: desc + example: desc + enum: + - normal + - desc + - asc + type: string responses: '200': description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/FlagList' + '404': + description: Not Found content: application/json: schema: type: object properties: - object: - type: string - description: Distinguishes the user object. - const: user - id: - type: string - description: The unique ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - first_name: - type: - - string - - 'null' - description: The first name of the user. - example: Marcelina - last_name: - type: - - string - - 'null' - description: The last name of the user. - example: Davis - profile_picture_url: - type: - - string - - 'null' - description: A URL reference to an image representing the user. - example: https://workoscdn.com/images/v1/123abc - email: + message: type: string - description: The email address of the user. - example: marcelina.davis@example.com - email_verified: - type: boolean - description: Whether the user's email has been verified. - example: true - external_id: - type: - - string - - 'null' - description: The external ID of the user. - example: f1ffa2b2-c20b-4d39-be5c-212726e11222 - metadata: - type: object - additionalProperties: - type: string - maxLength: 600 - description: >- - Object containing metadata key/value pairs associated with - the user. - example: - timezone: America/New_York - propertyNames: - maxLength: 40 - maxProperties: 50 - last_sign_in_at: - format: date-time - type: - - string - - 'null' - description: The timestamp when the user last signed in. - example: '2025-06-25T19:07:33.155Z' - locale: - type: - - string - - 'null' - description: The user's preferred locale. - example: en-US - 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' + description: A human-readable description of the error. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - - object - - id - - first_name - - last_name - - profile_picture_url - - email - - email_verified - - external_id - - last_sign_in_at - - created_at - - updated_at + - message + tags: + - user-management.users.feature-flags + /user_management/users/{user_id}/authorized_applications: + get: + operationId: AuthorizedApplicationsController_list + summary: List authorized applications + description: Get a list of all Connect applications that the user has authorized. + parameters: + - name: user_id + required: true + in: path + description: The ID of the user. + schema: + example: user_01E4ZCR3C56J083X43JQXF3JK5 + type: string + - 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: number + - 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: + default: desc + example: desc + enum: + - normal + - desc + - asc + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AuthorizedConnectApplicationList' '404': description: Not Found content: @@ -20817,25 +14144,44 @@ paths: 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 tags: - - user-management.users + - user-management.users.authorized-applications + /user_management/users/{user_id}/authorized_applications/{application_id}: delete: - operationId: UserlandUsersController_delete - summary: Delete a user - description: >- - Permanently deletes a user in the current environment. It cannot be - undone. + operationId: AuthorizedApplicationsController_delete + summary: Delete an authorized application + description: Delete an existing Authorized Connect Application. parameters: - - name: id + - name: application_id required: true in: path - description: The unique ID of the user. + description: The ID or client ID of the application. + schema: + example: conn_app_01HXYZ123456789ABCDEFGHIJ + type: string + - name: user_id + required: true + in: path + description: The ID of the user. schema: example: user_01E4ZCR3C56J083X43JQXF3JK5 type: string responses: - '200': - description: OK + '204': + description: No Content '404': description: Not Found content: @@ -20850,192 +14196,51 @@ paths: required: - message tags: - - user-management.users - /user_management/users/{id}/email_verification/confirm: - post: - operationId: UserlandUsersController_emailVerification - summary: Verify email - description: Verifies an email address using the one-time code received by the user. + - user-management.users.authorized-applications + /user_management/users/{user_id}/connected_accounts/{slug}: + get: + operationId: DataIntegrationsUserManagementController_getUserDataInstallation + summary: Get a connected account + description: >- + Retrieves a user's [connected + account](/reference/pipes/connected-account) for a specific provider. parameters: - - name: id + - name: user_id required: true in: path - description: The ID of the user. + description: A [User](/reference/authkit/user) identifier. schema: - type: string example: user_01EHZNVPK3SFK441A1RGBFSHRT - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/VerifyEmailAddressDto' + type: string + - name: slug + required: true + in: path + description: >- + The slug identifier of the provider (e.g., `github`, `slack`, + `notion`). + schema: + example: github + type: string + - name: organization_id + required: false + in: query + description: >- + An [Organization](/reference/organization) identifier. Optional + parameter if the connection is scoped to an organization. + schema: + example: org_01EHZNVPK3SFK441A1RGBFSHRT + type: string responses: '200': - description: OK + description: The connected account was retrieved successfully. content: application/json: schema: - type: object - properties: - user: - type: object - properties: - object: - type: string - description: Distinguishes the user object. - const: user - id: - type: string - description: The unique ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - first_name: - type: - - string - - 'null' - description: The first name of the user. - example: Marcelina - last_name: - type: - - string - - 'null' - description: The last name of the user. - example: Davis - profile_picture_url: - type: - - string - - 'null' - description: A URL reference to an image representing the user. - example: https://workoscdn.com/images/v1/123abc - email: - type: string - description: The email address of the user. - example: marcelina.davis@example.com - email_verified: - type: boolean - description: Whether the user's email has been verified. - example: true - external_id: - type: - - string - - 'null' - description: The external ID of the user. - example: f1ffa2b2-c20b-4d39-be5c-212726e11222 - metadata: - type: object - additionalProperties: - type: string - maxLength: 600 - description: >- - Object containing metadata key/value pairs associated - with the user. - example: - timezone: America/New_York - propertyNames: - maxLength: 40 - maxProperties: 50 - last_sign_in_at: - format: date-time - type: - - string - - 'null' - description: The timestamp when the user last signed in. - example: '2025-06-25T19:07:33.155Z' - locale: - type: - - string - - 'null' - description: The user's preferred locale. - example: en-US - 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 - - first_name - - last_name - - profile_picture_url - - email - - email_verified - - external_id - - last_sign_in_at - - created_at - - updated_at - description: The user whose email was verified. - required: - - user - '400': - description: Bad Request - content: - application/json: - schema: - oneOf: - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: email_previously_verified - const: email_previously_verified - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: email_verification_code_previously_used - const: email_verification_code_previously_used - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: email_verification_code_expired - const: email_verification_code_expired - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: email_verification_code_incorrect - const: email_verification_code_incorrect - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - '404': - description: Not Found + $ref: '#/components/schemas/ConnectedAccount' + '401': + description: The request is missing a valid API key. + '404': + description: The user, organization, or connected account was not found. content: application/json: schema: @@ -21047,259 +14252,222 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - '422': - description: Unprocessable Entity + tags: + - user-management.data-providers + delete: + operationId: DataIntegrationsUserManagementController_deleteUserDataInstallation + summary: Delete a connected account + description: >- + Disconnects WorkOS's account for the user, including removing any stored + access and refresh tokens. The user will need to reauthorize if they + want to reconnect. This does not revoke access on the provider side. + parameters: + - name: user_id + required: true + in: path + description: A [User](/reference/authkit/user) identifier. + schema: + example: user_01EHZNVPK3SFK441A1RGBFSHRT + type: string + - name: slug + required: true + in: path + description: >- + The slug identifier of the provider (e.g., `github`, `slack`, + `notion`). + schema: + example: github + type: string + - name: organization_id + required: false + in: query + description: >- + An [Organization](/reference/organization) identifier. Optional + parameter if the connection is scoped to an organization. + schema: + example: org_01EHZNVPK3SFK441A1RGBFSHRT + type: string + responses: + '204': + description: The connected account was deleted successfully. + '401': + description: The request is missing a valid API key. + '404': + description: The user, organization, or connected account was not found. content: application/json: schema: type: object properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_request_parameters - const: invalid_request_parameters message: type: string description: A human-readable description of the error. - example: Validation failed. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - - code - message tags: - - user-management.users - /user_management/users/{id}/email_verification/send: - post: - operationId: UserlandUsersController_sendVerificationEmail - summary: Send verification email + - user-management.data-providers + /user_management/users/{user_id}/data_providers: + get: + operationId: DataIntegrationsUserManagementController_getUserDataIntegrations + summary: List providers description: >- - Sends an email that contains a one-time code used to verify a user’s - email address. + Retrieves a list of available providers and the user's connection status + for each. Returns all providers configured for your environment, along + with the user's [connected account](/reference/pipes/connected-account) + information where applicable. parameters: - - name: id + - name: user_id required: true in: path - description: The ID of the user. + description: >- + A [User](/reference/authkit/user) identifier to list providers and + connected accounts for. schema: - type: string example: user_01EHZNVPK3SFK441A1RGBFSHRT + type: string + - name: organization_id + required: false + in: query + description: >- + An [Organization](/reference/organization) identifier. Optional + parameter to filter connections for a specific organization. + schema: + example: org_01EHZNVPK3SFK441A1RGBFSHRT + type: string responses: '200': - description: OK + description: The list of data providers was retrieved successfully. content: application/json: schema: - type: object - properties: - user: - type: object - properties: - object: - type: string - description: Distinguishes the user object. - const: user - id: - type: string - description: The unique ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - first_name: - type: - - string - - 'null' - description: The first name of the user. - example: Marcelina - last_name: - type: - - string - - 'null' - description: The last name of the user. - example: Davis - profile_picture_url: - type: - - string - - 'null' - description: A URL reference to an image representing the user. - example: https://workoscdn.com/images/v1/123abc - email: - type: string - description: The email address of the user. - example: marcelina.davis@example.com - email_verified: - type: boolean - description: Whether the user's email has been verified. - example: true - external_id: - type: - - string - - 'null' - description: The external ID of the user. - example: f1ffa2b2-c20b-4d39-be5c-212726e11222 - metadata: - type: object - additionalProperties: - type: string - maxLength: 600 - description: >- - Object containing metadata key/value pairs associated - with the user. - example: - timezone: America/New_York - propertyNames: - maxLength: 40 - maxProperties: 50 - last_sign_in_at: - format: date-time - type: - - string - - 'null' - description: The timestamp when the user last signed in. - example: '2025-06-25T19:07:33.155Z' - locale: - type: - - string - - 'null' - description: The user's preferred locale. - example: en-US - 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 - - first_name - - last_name - - profile_picture_url - - email - - email_verified - - external_id - - last_sign_in_at - - created_at - - updated_at - description: The user to whom the verification email was sent. - required: - - user - '400': - description: Bad Request + $ref: '#/components/schemas/DataIntegrationsListResponse' + '401': + description: The request is missing a valid API key. + '404': + description: The user or organization was not found. content: application/json: schema: type: object properties: - code: - type: string - description: The error code identifying the type of error. - example: email_already_verified - const: email_already_verified message: type: string description: A human-readable description of the error. - example: Request could not be processed. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - - code - message - '404': - description: Not Found + tags: + - user-management.data-providers + /user_management/users/{userlandUserId}/auth_factors: + post: + operationId: UserlandUserAuthenticationFactorsController_create + summary: Enroll an authentication factor + description: >- + Enrolls a user in a new [authentication + factor](/reference/authkit/mfa/authentication-factor). + parameters: + - name: userlandUserId + required: true + in: path + description: The ID of the [user](/reference/authkit/user). + schema: + example: user_01E4ZCR3C56J083X43JQXF3JK5 + type: string + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/EnrollUserlandUserAuthenticationFactorDto' + responses: + '201': + description: Created 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 - '429': - description: '' + $ref: >- + #/components/schemas/UserlandUserAuthenticationFactorEnrollResponse + '422': + description: Unprocessable Entity content: application/json: schema: type: object properties: - code: - type: string - description: The error code identifying the type of error. - example: daily_quota_exceeded - const: daily_quota_exceeded message: type: string description: A human-readable description of the error. - example: Request could not be processed. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - - code - message tags: - - user-management.users - /user_management/users/{id}/identities: + - user-management.multi-factor-authentication get: - operationId: UserlandUserIdentitiesController_get - summary: Get user identities + operationId: UserlandUserAuthenticationFactorsController_list + summary: List authentication factors description: >- - Get a list of identities associated with the user. A user can have - multiple associated identities after going through [identity - linking](/authkit/identity-linking). Currently only OAuth identities are - supported. More provider types may be added in the future. + Lists the [authentication + factors](/reference/authkit/mfa/authentication-factor) for a user. parameters: - - name: id + - name: userlandUserId required: true in: path - description: The unique ID of the user. + description: The ID of the [user](/reference/authkit/user). schema: example: user_01E4ZCR3C56J083X43JQXF3JK5 type: string - responses: - '200': - description: OK - content: - application/json: - schema: - type: array - items: - type: object - properties: - idp_id: - type: string - description: >- - The unique ID of the user in the external identity - provider. - example: 4F42ABDE-1E44-4B66-824A-5F733C037A6D - type: - type: string - description: The type of the identity. - const: OAuth - provider: - type: string - enum: - - AppleOAuth - - BitbucketOAuth - - DiscordOAuth - - GithubOAuth - - GitLabOAuth - - GoogleOAuth - - IntuitOAuth - - LinkedInOAuth - - MicrosoftOAuth - - SalesforceOAuth - - SlackOAuth - - VercelMarketplaceOAuth - - VercelOAuth - - XeroOAuth - description: The type of OAuth provider for the identity. - example: MicrosoftOAuth - required: - - idp_id - - type - - provider - '404': - description: Not Found + - 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. + schema: + example: obj_1234567890 + 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. + schema: + example: obj_1234567890 + 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: number + - name: order + required: false + in: query + description: Order the results by the creation time. + schema: + default: desc + example: desc + enum: + - normal + - desc + - asc + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/UserlandUserAuthenticationFactorList' + '422': + description: Unprocessable Entity content: application/json: schema: @@ -21312,20 +14480,13 @@ paths: required: - message tags: - - user-management.users - /user_management/users/{id}/sessions: + - user-management.multi-factor-authentication + /webhook_endpoints: get: - operationId: UserlandUserSessionsController_list - summary: List sessions - description: Get a list of all active sessions for a specific user. + operationId: WebhookEndpointsController_list + summary: List Webhook Endpoints + description: Get a list of all of your existing webhook endpoints. parameters: - - name: id - required: true - in: path - description: The ID of the user. - schema: - type: string - example: user_01EHZNVPK3SFK441A1RGBFSHRT - name: before required: false in: query @@ -21380,3906 +14541,5698 @@ paths: type: string responses: '200': - description: OK + description: List of webhook endpoints. content: application/json: schema: - allOf: + $ref: '#/components/schemas/WebhookEndpointList' + tags: + - webhooks + post: + operationId: WebhookEndpointsController_create + summary: Create a Webhook Endpoint + description: Create a new webhook endpoint to receive event notifications. + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateWebhookEndpointDto' + responses: + '201': + description: Webhook endpoint created successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/WebhookEndpointJson' + '409': + description: A Webhook Endpoint with the same endpoint URL already exists. + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: duplicate_endpoint + const: duplicate_endpoint + 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: + oneOf: - type: object properties: - object: + code: type: string - description: Indicates this is a list response. - const: list - 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: session_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: session_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: >- - Pagination cursors for navigating between pages of - results. + description: The error code identifying the type of error. + example: invalid_url + const: invalid_url + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message - type: object properties: - data: + code: + type: string + description: The error code identifying the type of error. + example: invalid_request_parameters + const: invalid_request_parameters + message: + type: string + description: A human-readable description of the error. + example: Validation failed. + errors: type: array - description: The list of records for the current page. items: type: object properties: - object: - type: string - description: Distinguishes the session object. - const: session - id: + code: type: string - description: The unique ID of the session. - example: session_01H93ZY4F80QPBEZ1R5B2SHQG8 - impersonator: - type: object - properties: - email: - type: string - description: >- - The email address of the WorkOS Dashboard - user who is impersonating the user. - example: admin@foocorp.com - reason: - type: - - string - - 'null' - description: >- - The justification the impersonator gave for - impersonating the user. - example: >- - Investigating an issue with the customer's - account. - required: - - email - - reason - description: >- - Information about the impersonator if this - session was created via impersonation. - ip_address: - type: - - string - - 'null' - description: >- - The IP address from which the session was - created. - example: 198.51.100.42 - organization_id: + description: The validation error code. + example: unknown_event_type + message: type: string description: >- - The ID of the organization this session is - associated with. - example: org_01H945H0YD4F97JN9MATX7BYAG - user_agent: - type: - - string - - 'null' - description: >- - The user agent string from the device that - created the session. - example: >- - Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) - AppleWebKit/537.36 - user_id: - type: string - description: The ID of the user this session belongs to. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - auth_method: - type: string - enum: - - cross_app_auth - - external_auth - - impersonation - - magic_code - - migrated_session - - oauth - - passkey - - password - - sso - - unknown - description: >- - The authentication method used to create this - session. - example: sso - status: - type: string - enum: - - active - - expired - - revoked - description: The current status of the session. - example: active - expires_at: - format: date-time - type: string - description: The timestamp when the session expires. - example: '2026-01-15T12:00:00.000Z' - ended_at: - format: date-time - type: - - string - - 'null' - description: The timestamp when the session ended. - example: null - 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' + A human-readable description of the validation + error. + example: Invalid enum value. required: - - object - - id - - ip_address - - user_agent - - user_id - - auth_method - - status - - expires_at - - ended_at - - created_at - - updated_at + - code + - message + description: The list of validation errors. + required: + - code + - message + - errors + tags: + - webhooks + /webhook_endpoints/{id}: + delete: + operationId: WebhookEndpointsController_delete + summary: Delete a Webhook Endpoint + description: Delete an existing webhook endpoint. + parameters: + - name: id + required: true + in: path + description: Unique identifier of the Webhook Endpoint. + schema: + type: string + example: we_0123456789 + responses: + '204': + description: Webhook endpoint deleted successfully. '404': - description: Not Found + description: Webhook endpoint not found. content: application/json: schema: type: object properties: + code: + type: string + description: The error code identifying the type of error. + example: entity_not_found + const: entity_not_found message: type: string description: A human-readable description of the error. - example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + example: Request could not be processed. required: + - code - message - '422': - description: Unprocessable Entity + tags: + - webhooks + /widgets/token: + post: + operationId: WidgetsPublicController_issueWidgetSessionToken + summary: Generate a widget token + description: >- + Generate a widget token scoped to an organization and user with the + specified scopes. + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/WidgetSessionTokenDto' + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/WidgetSessionTokenResponse' + '400': + description: Bad Request + content: + application/json: + schema: + oneOf: + - type: object + properties: + message: + type: string + description: A human-readable description of the error. + example: >- + Organization not found: + 'org_01EHQMYV6MBK39QC5PZXHY59C3'. + required: + - message + - type: object + properties: + message: + type: array + items: + type: string + description: A list of validation error messages. + example: + - organization_id must be a string + error: + type: string + description: The error type. + example: Bad Request + required: + - message + - error + '404': + description: Not Found content: application/json: schema: type: object properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_request_parameters - const: invalid_request_parameters message: type: string description: A human-readable description of the error. - example: Validation failed. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - - code - message - tags: - - user-management.users - /user_management/users/{userId}/feature-flags: - get: - operationId: UserlandUserFeatureFlagsController_list - summary: List enabled feature flags for a user - description: >- - Get a list of all enabled feature flags for the provided user. This - includes feature flags enabled specifically for the user as well as any - organizations that the user is a member of. - parameters: - - name: userId - required: true - in: path - description: The ID of the user. - schema: - example: user_01E4ZCR3C56J083X43JQXF3JK5 - type: string - - 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. - schema: - example: obj_1234567890 - 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. - schema: - example: obj_1234567890 - 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: number - - name: order - required: false - in: query - description: Order the results by the creation time. - schema: - default: desc - example: desc - enum: - - normal - - desc - - asc - type: string - responses: - '200': - description: OK + '422': + description: Unprocessable Entity content: application/json: schema: type: object properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - type: object - properties: - object: - type: string - description: Distinguishes the Feature Flag object. - const: feature_flag - id: - type: string - description: Unique identifier of the Feature Flag. - example: flag_01EHZNVPK3SFK441A1RGBFSHRT - slug: - type: string - description: A unique key to reference the Feature Flag. - example: advanced-analytics - name: - type: string - description: >- - A descriptive name for the Feature Flag. This field - does not need to be unique. - example: Advanced Analytics - description: - type: - - string - - 'null' - description: A description for the Feature Flag. - example: Enable advanced analytics dashboard feature - owner: - description: The owner of the Feature Flag. - oneOf: - - type: object - properties: - email: - type: string - description: The email address of the flag owner. - example: jane@example.com - first_name: - type: - - string - - 'null' - description: The first name of the flag owner. - example: Jane - last_name: - type: - - string - - 'null' - description: The last name of the flag owner. - example: Doe - required: - - email - - first_name - - last_name - - type: 'null' - tags: - type: array - items: - type: string - description: >- - Labels assigned to the Feature Flag for categorizing - and filtering. - example: - - reports - enabled: - type: boolean - description: >- - Specifies whether the Feature Flag is active for the - current environment. - example: true - default_value: - type: boolean - description: >- - The value returned for users and organizations who - don't match any configured targeting rules. - example: false - 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 - - owner - - tags - - enabled - - default_value - - created_at - - updated_at - 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: flag_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: flag_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: >- - Pagination cursors for navigating between pages of - results. - required: - - object - - data - - list_metadata - '404': - description: Not Found - content: - application/json: - schema: - type: object - properties: - message: + message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message tags: - - user-management.users.feature-flags - /user_management/users/{user_id}/authorized_applications: - get: - operationId: AuthorizedApplicationsController_list - summary: List authorized applications - description: Get a list of all Connect applications that the user has authorized. - parameters: - - name: user_id - required: true - in: path - description: The ID of the user. - schema: - example: user_01E4ZCR3C56J083X43JQXF3JK5 - type: string - - 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: number - - name: order - required: false - in: query + - widgets +info: + title: WorkOS + 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 +tags: + - name: admin-portal + description: Endpoints for the Admin Portal API. + - name: api_keys + description: Manage API keys for environments. + - name: application.client-secrets + description: Manage client secrets for Connect Applications. + - name: applications + description: Manage Connect Applications. + - name: audit-logs + description: Create and query audit log events. + - name: authorization + description: Authorization and access control. + - name: connections + description: Manage SSO connections. + - name: directories + description: Manage directories. + - name: directory-groups + description: Manage directory groups. + - name: directory-users + description: Manage directory users. + - name: events + description: Query events and event streams. + - name: feature-flags + description: Manage feature flags. + - name: feature-flags.targets + description: Manage feature flag targets. + - name: multi-factor-auth + description: Multi-factor authentication factor management. + - name: multi-factor-auth.challenges + description: Multi-factor authentication challenge verification. + - name: organizations + description: Manage organizations. + - name: organizations.api_keys + description: Manage organization-scoped API keys. + - name: organizations.feature-flags + description: Manage organization-scoped feature flags. + - name: permissions + description: Manage permissions. + - name: pipes + description: Data integration endpoints. + - name: radar + description: Radar fraud detection. + - name: sso + description: Single Sign-On endpoints. + - name: user-management.authentication + description: User authentication endpoints. + - name: user-management.cors-origins + description: Manage CORS origins for user management. + - name: user-management.data-providers + description: Manage data providers. + - name: user-management.invitations + description: Manage user invitations. + - name: user-management.jwt-template + description: Manage JWT templates. + - name: user-management.magic-auth + description: Magic auth endpoints. + - name: user-management.multi-factor-authentication + description: Multi-factor authentication endpoints. + - name: user-management.organization-membership + description: Manage user organization memberships. + - name: user-management.redirect-uris + description: Manage redirect URIs. + - name: user-management.session-tokens + description: Session token verification keys. + - name: user-management.users + description: Manage users. + - name: user-management.users.authorized-applications + description: Manage authorized applications for users. + - name: user-management.users.feature-flags + description: Manage user-scoped feature flags. + - name: webhooks + description: Manage webhooks. + - name: widgets + description: Widget endpoints. + - name: workos-connect + description: >- + A unified interface that simplifies authentication and authorization + across customers, partners, and external SaaS tools. +servers: + - url: https://api.workos.com + description: Production + - url: https://api.workos-test.com + description: Staging +components: + 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. + schemas: + UserObject: + type: object + properties: + id: + type: string 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: - default: desc - example: desc - enum: - - normal - - desc - - asc + Your application's user identifier, which will be stored as an + [`external_id`](/authkit/metadata/external-identifiers). Used for + upserting and deduplication. + example: user_12345 + email: + type: string + description: The user's email address. + example: marcelina.davis@example.com + first_name: + type: string + description: The user's first name. + example: Marcelina + last_name: + type: string + description: The user's last name. + example: Davis + metadata: + type: object + description: A set of key-value pairs to attach to the user. + additionalProperties: type: string - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - type: object - properties: - object: - type: string - description: >- - Distinguishes the authorized connect application - object. - const: authorized_connect_application - id: - type: string - description: The unique ID of the authorized connect application. - example: aca_01HXYZ123456789ABCDEFGHIJ - granted_scopes: - type: array - items: - type: string - description: The scopes granted by the user to the application. - example: - - openid - - profile - - email - application: - allOf: - - type: object - properties: - object: - type: string - description: >- - Distinguishes the connect application - object. - example: connect_application - const: connect_application - id: - type: string - description: The unique ID of the connect application. - example: conn_app_01HXYZ123456789ABCDEFGHIJ - client_id: - type: string - description: The client ID of the connect application. - example: client_01HXYZ123456789ABCDEFGHIJ - description: - type: - - string - - 'null' - description: A description of the connect application. - example: >- - A sample application for managing user - connections. - name: - type: string - description: The name of the connect application. - example: My Application - scopes: - type: array - items: - type: string - description: The scopes available for this application. - example: - - openid - - profile - - email - 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 - - client_id - - description - - name - - scopes - - created_at - - updated_at - - oneOf: - - allOf: - - type: object - properties: - application_type: - type: string - description: The type of the application. - const: oauth - redirect_uris: - type: array - items: - type: object - properties: - uri: - type: string - format: uri - description: The redirect URI for the application. - example: https://example.com/callback - default: - type: boolean - description: >- - Whether this is the default redirect - URI. - example: true - required: - - uri - - default - description: >- - The redirect URIs configured for this - application. - uses_pkce: - type: boolean - description: >- - Whether the application uses PKCE for - authorization. - example: true - required: - - application_type - - redirect_uris - - uses_pkce - - oneOf: - - type: object - properties: - is_first_party: - type: boolean - description: >- - Whether the application is a first-party - application. - example: true - const: true - required: - - is_first_party - - type: object - properties: - is_first_party: - type: boolean - description: >- - Whether the application is a first-party - application. - example: false - const: false - was_dynamically_registered: - type: boolean - description: >- - Whether the application was dynamically - registered. - example: false - const: false - organization_id: - type: string - description: >- - The ID of the organization the - application belongs to. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - required: - - is_first_party - - was_dynamically_registered - - organization_id - - type: object - properties: - is_first_party: - type: boolean - description: >- - Whether the application is a first-party - application. - example: false - const: false - was_dynamically_registered: - type: boolean - description: >- - Whether the application was dynamically - registered. - example: true - const: true - required: - - is_first_party - - was_dynamically_registered - - type: object - properties: - application_type: - type: string - description: The type of the application. - example: m2m - const: m2m - organization_id: - type: string - description: >- - The ID of the organization the - application belongs to. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - required: - - application_type - - organization_id - required: - - object - - id - - granted_scopes - - application - 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: aca_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: aca_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: >- - Pagination cursors for navigating between pages of - results. - required: - - object - - data - - list_metadata - '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 - tags: - - user-management.users.authorized-applications - x-feature-flag: connect-management-api - /user_management/users/{user_id}/authorized_applications/{application_id}: - delete: - operationId: AuthorizedApplicationsController_delete - summary: Delete an authorized application - description: Delete an existing Authorized Connect Application. - parameters: - - name: application_id - required: true - in: path - description: The ID or client ID of the application. - schema: - example: conn_app_01HXYZ123456789ABCDEFGHIJ - type: string - - name: user_id - required: true - in: path - description: The ID of the user. - schema: - example: user_01E4ZCR3C56J083X43JQXF3JK5 - type: string - responses: - '204': - description: No Content - '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 - tags: - - user-management.users.authorized-applications - x-feature-flag: connect-management-api - /user_management/users/{user_id}/connected_accounts/{slug}: - get: - operationId: DataIntegrationsUserManagementController_getUserDataInstallation - summary: Get a connected account - description: >- - Retrieves a user's [connected - account](/reference/pipes/connected-account) for a specific provider. - parameters: - - name: user_id - required: true - in: path - description: A [User](/reference/authkit/user) identifier. - schema: - example: user_01EHZNVPK3SFK441A1RGBFSHRT - type: string - - name: slug - required: true - in: path - description: >- - The slug identifier of the provider (e.g., `github`, `slack`, - `notion`). - schema: - example: github - type: string - - name: organization_id - required: false - in: query + maxLength: 600 + maxProperties: 50 + example: + department: Engineering + role: Developer + propertyNames: + maxLength: 40 + required: + - id + - email + UserConsentOption: + type: object + properties: + claim: + type: string + description: The claim name for this consent option. + example: tos_accepted + type: + type: string + description: The type of consent option. + const: enum + label: + type: string + description: A human-readable label for this consent option. + example: Terms of Service + choices: + type: array + description: The available choices for this consent option. + items: + type: object + properties: + value: + type: string + description: The value of this choice. + example: accepted + label: + type: string + description: A human-readable label for this choice. + example: I accept the Terms of Service + example: + - value: accepted + label: I accept the Terms of Service + required: + - claim + - type + - label + - choices + UserManagementLoginRequest: + type: object + properties: + external_auth_id: + type: string + description: Identifier provided when AuthKit redirected to your login page. + example: ext_auth_01HXYZ123456789ABCDEFGHIJ + user: + description: The user to create or update in AuthKit. + $ref: '#/components/schemas/UserObject' + user_consent_options: description: >- - An [Organization](/reference/organization) identifier. Optional - parameter if the connection is scoped to an organization. - schema: - example: org_01EHZNVPK3SFK441A1RGBFSHRT - type: string - responses: - '200': - description: The connected account was retrieved successfully. - content: - application/json: - schema: - type: object - properties: - object: - type: string - description: Distinguishes the connected account object. - const: connected_account - id: - type: string - description: The unique identifier of the connected account. - example: data_installation_01EHZNVPK3SFK441A1RGBFSHRT - user_id: - type: - - string - - 'null' - description: >- - The [User](/reference/authkit/user) identifier associated - with this connection. - example: user_01EHZNVPK3SFK441A1RGBFSHRT - organization_id: - type: - - string - - 'null' - description: >- - The [Organization](/reference/organization) identifier - associated with this connection, or `null` if not scoped - to an organization. - example: null - scopes: - type: array - items: - type: string - description: The OAuth scopes granted for this connection. - example: - - repo - - user:email - state: - type: string - enum: - - connected - - needs_reauthorization - - disconnected - description: >- - The state of the connected account: - - - `connected`: The connection is active and tokens are - valid. - - - `needs_reauthorization`: The user needs to reauthorize - the connection, typically because required scopes have - changed. - - - `disconnected`: The connection has been disconnected. - example: connected - created_at: - type: string - description: The timestamp when the connection was created. - example: '2024-01-16T14:20:00.000Z' - updated_at: - type: string - description: The timestamp when the connection was last updated. - example: '2024-01-16T14:20:00.000Z' - required: - - object - - id - - user_id - - organization_id - - scopes - - state - - created_at - - updated_at - '401': - description: The request is missing a valid API key. - '404': - description: The user, organization, or connected account was 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 - tags: - - user-management.data-providers - delete: - operationId: DataIntegrationsUserManagementController_deleteUserDataInstallation - summary: Delete a connected account - description: >- - Disconnects WorkOS's account for the user, including removing any stored - access and refresh tokens. The user will need to reauthorize if they - want to reconnect. This does not revoke access on the provider side. - parameters: - - name: user_id - required: true - in: path - description: A [User](/reference/authkit/user) identifier. - schema: - example: user_01EHZNVPK3SFK441A1RGBFSHRT - type: string - - name: slug - required: true - in: path - description: >- - The slug identifier of the provider (e.g., `github`, `slack`, - `notion`). - schema: - example: github + Array of [User Consent + Options](/reference/workos-connect/standalone/user-consent-options) + to store with the session. + type: array + items: + $ref: '#/components/schemas/UserConsentOption' + required: + - external_auth_id + - user + ValidateApiKeyDto: + type: object + properties: + value: + type: string + description: The value for an API key. + example: sk_example_1234567890abcdef + required: + - value + RedirectUriDto: + type: object + properties: + uri: + type: string + description: The redirect URI. + example: https://example.com/callback + default: + type: + - boolean + - 'null' + description: Whether this is the default redirect URI. + example: true + required: + - uri + CreateOAuthApplicationDto: + type: object + properties: + name: + type: string + description: The name of the application. + example: My Application + application_type: + type: string + description: The type of application to create. + const: oauth + description: + type: + - string + - 'null' + description: A description for the application. + example: An application for managing user access + scopes: + description: The OAuth scopes granted to the application. + example: &ref_0 + - openid + - profile + - email + type: + - array + - 'null' + items: type: string - - name: organization_id - required: false - in: query + redirect_uris: + description: Redirect URIs for the application. + example: + - uri: https://example.com/callback + default: true + type: + - array + - 'null' + items: + $ref: '#/components/schemas/RedirectUriDto' + uses_pkce: + type: + - boolean + - 'null' + description: Whether the application uses PKCE (Proof Key for Code Exchange). + example: true + is_first_party: + type: boolean description: >- - An [Organization](/reference/organization) identifier. Optional - parameter if the connection is scoped to an organization. - schema: - example: org_01EHZNVPK3SFK441A1RGBFSHRT - type: string - responses: - '204': - description: The connected account was deleted successfully. - '401': - description: The request is missing a valid API key. - '404': - description: The user, organization, or connected account was 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 - tags: - - user-management.data-providers - /user_management/users/{user_id}/data_providers: - get: - operationId: DataIntegrationsUserManagementController_getUserDataIntegrations - summary: List providers - description: >- - Retrieves a list of available providers and the user's connection status - for each. Returns all providers configured for your environment, along - with the user's [connected account](/reference/pipes/connected-account) - information where applicable. - parameters: - - name: user_id - required: true - in: path + Whether this is a first-party application. Third-party applications + require an organization_id. + example: true + organization_id: + type: + - string + - 'null' description: >- - A [User](/reference/authkit/user) identifier to list providers and - connected accounts for. - schema: - example: user_01EHZNVPK3SFK441A1RGBFSHRT + The organization ID this application belongs to. Required when + is_first_party is false. + example: org_01EHZNVPK3SFK441A1RGBFSHRT + required: + - name + - application_type + - is_first_party + CreateM2MApplicationDto: + type: object + properties: + name: + type: string + description: The name of the application. + example: My Application + application_type: + type: string + description: The type of application to create. + const: m2m + description: + type: + - string + - 'null' + description: A description for the application. + example: An application for managing user access + scopes: + description: The OAuth scopes granted to the application. + example: *ref_0 + type: + - array + - 'null' + items: type: string - - name: organization_id - required: false - in: query - description: >- - An [Organization](/reference/organization) identifier. Optional - parameter to filter connections for a specific organization. - schema: - example: org_01EHZNVPK3SFK441A1RGBFSHRT + organization_id: + type: string + description: The organization ID this application belongs to. + example: org_01EHZNVPK3SFK441A1RGBFSHRT + required: + - name + - application_type + - organization_id + UpdateOAuthApplicationDto: + type: object + properties: + name: + type: string + description: The name of the application. + example: My Application + description: + type: + - string + - 'null' + description: A description for the application. + example: An application for managing user access + scopes: + description: The OAuth scopes granted to the application. + example: + - openid + - profile + - email + type: + - array + - 'null' + items: type: string - responses: - '200': - description: The list of data providers was retrieved successfully. - content: - application/json: - schema: - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - type: object - properties: - object: - type: string - description: Distinguishes the data provider object. - const: data_provider - id: - type: string - description: The unique identifier of the provider. - example: data_integration_01EHZNVPK3SFK441A1RGBFSHRT - name: - type: string - description: >- - The display name of the provider (e.g., "GitHub", - "Slack"). - example: GitHub - description: - type: - - string - - 'null' - description: >- - A description of the provider explaining how it will - be used, if configured. - example: Connect your GitHub account to access repositories. - slug: - type: string - description: >- - The slug identifier used in API calls (e.g., - `github`, `slack`, `notion`). - example: github - integration_type: - type: string - description: The type of integration (e.g., `github`, `slack`). - example: github - credentials_type: - type: string - description: >- - The type of credentials used by the provider (e.g., - `oauth2`). - example: oauth2 - scopes: - description: >- - The OAuth scopes configured for this provider, or - `null` if none are configured. - example: - - repo - - user:email - oneOf: - - type: array - items: - type: string - - type: 'null' - ownership: - type: string - enum: - - userland_user - - organization - description: >- - Whether the provider is owned by a user or - organization. - created_at: - type: string - description: The timestamp when the provider was created. - example: '2024-01-15T10:30:00.000Z' - updated_at: - type: string - description: The timestamp when the provider was last updated. - example: '2024-01-15T10:30:00.000Z' - integrationType: - type: string - deprecated: true - description: Use integration_type instead. - credentialsType: - type: string - deprecated: true - description: Use credentials_type instead. - createdAt: - type: string - deprecated: true - description: Use created_at instead. - updatedAt: - type: string - deprecated: true - description: Use updated_at instead. - connected_account: - description: >- - The user's [connected - account](/reference/pipes/connected-account) for - this provider, or `null` if the user has not - connected. - oneOf: - - type: object - properties: - object: - type: string - description: Distinguishes the connected account object. - const: connected_account - id: - type: string - description: >- - The unique identifier of the connected - account. - example: data_installation_01EHZNVPK3SFK441A1RGBFSHRT - user_id: - type: - - string - - 'null' - description: >- - The [User](/reference/authkit/user) - identifier associated with this connection. - example: user_01EHZNVPK3SFK441A1RGBFSHRT - organization_id: - type: - - string - - 'null' - description: >- - The [Organization](/reference/organization) - identifier associated with this connection, - or `null` if not scoped to an organization. - example: null - scopes: - type: array - items: - type: string - description: >- - The OAuth scopes granted for this - connection. - example: - - repo - - user:email - state: - type: string - enum: - - connected - - needs_reauthorization - - disconnected - description: >- - The state of the connected account: - - - `connected`: The connection is active and - tokens are valid. - - - `needs_reauthorization`: The user needs to - reauthorize the connection, typically - because required scopes have changed. - - - `disconnected`: The connection has been - disconnected. - example: connected - created_at: - type: string - description: >- - The timestamp when the connection was - created. - example: '2024-01-16T14:20:00.000Z' - updated_at: - type: string - description: >- - The timestamp when the connection was last - updated. - example: '2024-01-16T14:20:00.000Z' - userlandUserId: - type: - - string - - 'null' - deprecated: true - description: Use `user_id` instead. - organizationId: - type: - - string - - 'null' - deprecated: true - description: Use `organization_id` instead. - createdAt: - type: string - deprecated: true - description: Use `created_at` instead. - updatedAt: - type: string - deprecated: true - description: Use `updated_at` instead. - required: - - object - - id - - user_id - - organization_id - - scopes - - state - - created_at - - updated_at - - userlandUserId - - organizationId - - createdAt - - updatedAt - - type: 'null' - required: - - object - - id - - name - - description - - slug - - integration_type - - credentials_type - - scopes - - ownership - - created_at - - updated_at - - integrationType - - credentialsType - - createdAt - - updatedAt - - connected_account - description: >- - A list of [providers](/reference/pipes/provider), each - including a - [`connected_account`](/reference/pipes/connected-account) - field with the user's connection status. - required: - - object - - data - '401': - description: The request is missing a valid API key. - '404': - description: The user or organization was 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 - tags: - - user-management.data-providers - /user_management/users/{userlandUserId}/auth_factors: - post: - operationId: UserlandUserAuthenticationFactorsController_create - summary: Enroll an authentication factor - description: >- - Enrolls a user in a new [authentication - factor](/reference/authkit/mfa/authentication-factor). - parameters: - - name: userlandUserId - required: true - in: path - description: The ID of the [user](/reference/authkit/user). - schema: - example: user_01E4ZCR3C56J083X43JQXF3JK5 + redirect_uris: + description: Updated redirect URIs for the application. OAuth applications only. + example: + - uri: https://example.com/callback + default: true + type: + - array + - 'null' + items: + $ref: '#/components/schemas/RedirectUriDto' + CreateApplicationSecretDto: + type: object + properties: {} + AuditLogEventActorDto: + type: object + properties: + id: + type: string + description: Actor identifier. + example: user_TF4C5938 + type: + type: string + description: Actor type. + example: user + name: + type: string + description: Optional actor name. + example: Jon Smith + metadata: + type: object + description: Additional data associated with the event or entity. + example: + owner: user_01GBTCQ2 + maxProperties: 50 + additionalProperties: false + patternProperties: &ref_1 + ^[a-zA-Z0-9_-]{0,40}$: + anyOf: + - type: string + maxLength: 500 + - type: number + - type: boolean + required: + - id + - type + AuditLogEventTargetDto: + type: object + properties: + id: + type: string + description: Target identifier. + example: user_TF4C5938 + type: + type: string + description: Target type. + example: user + name: + type: string + description: Optional target name. + example: Jon Smith + metadata: + type: object + description: Additional data associated with the event or entity. + example: + owner: user_01GBTCQ2 + maxProperties: 50 + additionalProperties: false + patternProperties: *ref_1 + required: + - id + - type + AuditLogEventContextDto: + type: object + properties: + location: + type: string + description: IP Address or some other geolocation identifier. + example: 123.123.123.123 + user_agent: + type: string + description: User agent string. + example: Chrome/104.0.0.0 + required: + - location + AuditLogEventDto: + type: object + properties: + action: + type: string + description: Identifier of what happened. + example: user.signed_in + occurred_at: + type: string + description: ISO-8601 value of when the action occurred. + example: '2026-02-02T16:35:39.317Z' + actor: + description: The entity that performed the action. + $ref: '#/components/schemas/AuditLogEventActorDto' + targets: + description: The resources affected by the action. + type: array + items: + $ref: '#/components/schemas/AuditLogEventTargetDto' + context: + description: Additional context about where and how the action occurred. + $ref: '#/components/schemas/AuditLogEventContextDto' + metadata: + type: object + description: Additional data associated with the event or entity. + example: + owner: user_01GBTCQ2 + maxProperties: 50 + additionalProperties: false + patternProperties: *ref_1 + version: + type: number + description: What schema version the event is associated with. + example: 1 + required: + - action + - occurred_at + - actor + - targets + - context + AuditLogEventIngestionDto: + type: object + properties: + organization_id: + type: string + description: The unique ID of the Organization. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + event: + description: The audit log event to create. + $ref: '#/components/schemas/AuditLogEventDto' + required: + - organization_id + - event + AuditLogExportCreationDto: + type: object + properties: + organization_id: + type: string + description: The unique ID of the Organization. + example: org_01EHZNVPK3SFK441A1RGBFSHRT + range_start: + type: string + description: ISO-8601 value for start of the export range. + example: '2022-07-02T18:09:06.996Z' + range_end: + type: string + description: ISO-8601 value for end of the export range. + example: '2022-09-02T18:09:06.996Z' + actions: + description: List of actions to filter against. + example: + - user.signed_in + type: array + items: + type: string + actors: + description: Deprecated. Use `actor_names` instead. + deprecated: true + example: + - Jon Smith + type: array + items: + type: string + actor_names: + description: List of actor names to filter against. + example: + - Jon Smith + type: array + items: + type: string + actor_ids: + description: List of actor IDs to filter against. + example: + - user_01GBZK5MP7TD1YCFQHFR22180V + type: array + items: + type: string + targets: + description: List of target types to filter against. + example: + - team + type: array + items: + type: string + required: + - organization_id + - range_start + - range_end + UpdateAuditLogsRetentionDto: + type: object + properties: + retention_period_in_days: + type: number + description: >- + The number of days Audit Log events will be retained. Valid values + are `30` and `365`. + example: 30 + required: + - retention_period_in_days + AuditLogSchemaActorDto: + type: object + properties: + metadata: + type: object + description: JSON schema for actor metadata. + example: + type: object + properties: + role: + type: string + required: + - metadata + AuditLogSchemaTargetDto: + type: object + properties: + type: + type: string + description: The type of the target resource. + example: invoice + metadata: + type: object + description: Optional JSON schema for target metadata. + example: + type: object + properties: + cost: + type: number + required: + - type + AuditLogSchemaDto: + type: object + properties: + actor: + description: The metadata schema for the actor. + $ref: '#/components/schemas/AuditLogSchemaActorDto' + targets: + description: The list of targets for the schema. + type: array + items: + $ref: '#/components/schemas/AuditLogSchemaTargetDto' + metadata: + type: object + description: Optional JSON schema for event metadata. + example: + type: object + properties: + transactionId: + type: string + required: + - targets + ChallengeAuthenticationFactorDto: + type: object + properties: + sms_template: + type: string + description: >- + A custom template for the SMS message. Use the {{code}} placeholder + to include the verification code. + example: Your verification code is {{code}}. + CheckAuthorizationDto: + type: object + properties: + permission_slug: + type: string + description: The slug of the permission to check. + example: posts:create + resource_id: + type: string + description: The ID of the resource. + example: resource_01HXYZ123456789ABCDEFGHIJ + resource_external_id: + type: string + description: The external ID of the resource. + example: my-custom-id + resource_type_slug: + type: string + description: The slug of the resource type. + example: document + required: + - permission_slug + AssignRoleDto: + type: object + properties: + role_slug: + type: string + description: The slug of the role to assign. + example: editor + resource_id: + type: string + description: >- + The ID of the resource. Use either this or `resource_external_id` + and `resource_type_slug`. + example: authz_resource_01HXYZ123456789ABCDEFGH + resource_external_id: + type: string + description: The external ID of the resource. Requires `resource_type_slug`. + example: project-ext-456 + resource_type_slug: + type: string + description: The resource type slug. Required with `resource_external_id`. + example: project + required: + - role_slug + RemoveRoleDto: + type: object + properties: + role_slug: + type: string + description: The slug of the role to remove. + example: editor + resource_id: + type: string + description: >- + The ID of the resource. Use either this or `resource_external_id` + and `resource_type_slug`. + example: authz_resource_01HXYZ123456789ABCDEFGH + resource_external_id: + type: string + description: The external ID of the resource. Requires `resource_type_slug`. + example: external_01HXYZ123456789ABCDEFGH + resource_type_slug: + type: string + description: The resource type slug. Required with `resource_external_id`. + example: project + required: + - role_slug + SetRolePermissionsDto: + type: object + properties: + permissions: + description: The permission slugs to assign to the role. + example: + - billing:read + - billing:write + - invoices:manage + - reports:view + type: array + items: type: string - requestBody: - required: true + required: + - permissions + AddRolePermissionDto: + type: object + properties: + slug: + type: string + description: The slug of the permission to add to the role. + example: reports:export + required: + - slug + CreateOrganizationRoleDto: + type: object + properties: + slug: + type: string + maxLength: 48 + description: >- + A unique identifier for the role within the organization. Must begin + with 'org-' and contain only lowercase letters, numbers, hyphens, + and underscores. + example: org-billing-admin + name: + type: string + maxLength: 48 + description: A descriptive name for the role. + example: Billing Administrator + description: + type: + - string + - 'null' + maxLength: 150 + description: An optional description of the role's purpose. + example: Can manage billing and invoices + required: + - slug + - name + UpdateOrganizationRolePriorityOrderDto: + type: object + properties: + role_priority_order: + description: An ordered list of role slugs defining the priority order. + example: + - org-admin + type: array + items: + type: string + required: + - role_priority_order + UpdateOrganizationRoleDto: + type: object + properties: + name: + type: string + maxLength: 48 + description: A descriptive name for the role. + example: Finance Administrator + description: + type: + - string + - 'null' + maxLength: 150 + description: An optional description of the role's purpose. + example: Can manage all financial operations + 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 + 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 + CreateRoleDto: + type: object + properties: + slug: + type: string + maxLength: 48 + description: A unique slug for the role. + example: editor + name: + type: string + maxLength: 48 + description: A descriptive name for the role. + example: Editor + description: + type: + - string + - 'null' + maxLength: 150 + description: An optional description of the role. + example: Can edit resources + resource_type_slug: + type: string + maxLength: 48 + description: The slug of the resource type the role is scoped to. + example: default + required: + - slug + - name + UpdateRoleDto: + type: object + properties: + name: + type: string + maxLength: 48 + description: A descriptive name for the role. + example: Super Administrator + description: + type: + - string + - 'null' + maxLength: 150 + description: An optional description of the role. + example: Full administrative access to all resources + UpdateAuthorizationResourceDto: + type: object + properties: + name: + type: string + maxLength: 48 + description: A display name for the resource. + example: Updated Name + description: + type: + - string + - 'null' + maxLength: 150 + description: An optional description of the resource. + example: Updated description + parent_resource_id: + type: string + description: The ID of the parent resource. + example: authz_resource_01HXYZ123456789ABCDEFGHIJ + parent_resource_external_id: + type: string + description: The external ID of the parent resource. + example: parent-workspace-01 + parent_resource_type_slug: + type: string + description: The resource type slug of the parent resource. + example: workspace + CreateAuthorizationResourceDto: + type: object + properties: + external_id: + type: string + maxLength: 128 + description: An external identifier for the resource. + example: my-workspace-01 + name: + type: string + maxLength: 48 + description: A display name for the resource. + example: Acme Workspace + description: + type: + - string + - 'null' + maxLength: 150 + description: An optional description of the resource. + example: Primary workspace for the Acme team + resource_type_slug: + type: string + description: The slug of the resource type. + example: workspace + organization_id: + type: string + description: The ID of the organization this resource belongs to. + example: org_01EHQMYV6MBK39QC5PZXHY59C3 + parent_resource_id: + type: + - string + - 'null' + description: The ID of the parent resource. + example: authz_resource_01HXYZ123456789ABCDEFGHIJ + parent_resource_external_id: + type: string + description: The external ID of the parent resource. + example: parent-workspace-01 + parent_resource_type_slug: + type: string + description: The resource type slug of the parent resource. + example: workspace + required: + - external_id + - name + - resource_type_slug + - organization_id + CreateCorsOriginDto: + type: object + properties: + origin: + type: string + description: The origin URL to allow for CORS requests. + example: https://example.com + required: + - origin + UpdateJwtTemplateDto: + type: object + properties: content: - application/json: - schema: - $ref: '#/components/schemas/EnrollUserlandUserAuthenticationFactorDto' - responses: - '201': - description: Created - content: - application/json: - schema: - type: object - properties: - authentication_factor: - type: object - properties: - object: - type: string - description: Distinguishes the authentication factor object. - const: authentication_factor - id: - type: string - description: The unique ID of the factor. - example: auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ - type: - type: string - enum: - - generic_otp - - sms - - totp - - webauthn - description: The type of the factor to enroll. - example: totp - user_id: - type: string - description: The ID of the [user](/reference/authkit/user). - example: user_01E4ZCR3C56J083X43JQXF3JK5 - sms: - type: object - properties: - phone_number: - type: string - description: >- - The user's phone number for SMS-based - authentication. - example: '+15005550006' - required: - - phone_number - description: SMS-based authentication factor details. - totp: - oneOf: - - type: object - properties: - issuer: - type: string - description: >- - Your application or company name displayed in - the user's authenticator app. Defaults to your - WorkOS team name. - example: WorkOS - user: - type: string - description: >- - The user's account name displayed in their - authenticator app. Defaults to the user's - email. - example: user@example.com - secret: - type: string - description: >- - TOTP secret that can be manually entered into - some authenticator apps in place of scanning a - QR code. - example: JBSWY3DPEHPK3PXP - qr_code: - type: string - description: >- - Base64 encoded image containing scannable QR - code. - example: >- - data:image/png;base64,iVBORw0KGgoAAAANSUhEUg... - uri: - type: string - description: >- - The `otpauth` URI that is encoded by the - provided `qr_code`. - example: >- - otpauth://totp/WorkOS:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=WorkOS - required: - - issuer - - user - - secret - - qr_code - - uri - additionalProperties: false - - type: object - properties: - issuer: - type: string - description: >- - Your application or company name displayed in - the user's authenticator app. Defaults to your - WorkOS team name. - example: WorkOS - user: - type: string - description: >- - The user's account name displayed in their - authenticator app. Defaults to the user's - email. - example: user@example.com - required: - - issuer - - user - additionalProperties: false - description: TOTP-based authentication factor details. - 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 - - type - - created_at - - updated_at - description: >- - The [authentication - factor](/reference/authkit/mfa/authentication-factor) - object that represents the additional authentication - method used on top of the existing authentication - strategy. - authentication_challenge: - type: object - properties: - object: - type: string - description: Distinguishes the authentication challenge object. - const: authentication_challenge - id: - type: string - description: The unique ID of the authentication challenge. - example: auth_challenge_01FVYZ5QM8N98T9ME5BCB2BBMJ - expires_at: - format: date-time - type: string - description: >- - The timestamp when the challenge will expire. Does not - apply to TOTP factors. - example: '2026-01-15T12:00:00.000Z' - code: - type: string - description: The one-time code for the challenge. - example: '123456' - authentication_factor_id: - type: string - description: >- - The unique ID of the authentication factor the - challenge belongs to. - example: auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ - 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 - - authentication_factor_id - - created_at - - updated_at - description: >- - The [authentication - challenge](/reference/authkit/mfa/authentication-challenge) - object that is used to complete the authentication - process. - required: - - authentication_factor - - authentication_challenge - '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 - tags: - - user-management.multi-factor-authentication - get: - operationId: UserlandUserAuthenticationFactorsController_list - summary: List authentication factors - description: >- - Lists the [authentication - factors](/reference/authkit/mfa/authentication-factor) for a user. - parameters: - - name: userlandUserId - required: true - in: path - description: The ID of the [user](/reference/authkit/user). - schema: - example: user_01E4ZCR3C56J083X43JQXF3JK5 + type: string + description: The JWT template content as a Liquid template string. + example: '{"iss": "{{environment.id}}", "sub": "{{user.id}}"}' + required: + - content + CreateOrganizationDomainDto: + type: object + properties: + domain: + type: string + description: The domain to add to the organization. + example: foo-corp.com + organization_id: + type: string + description: The ID of the organization to add the domain to. + example: org_01EHQMYV6MBK39QC5PZXHY59C3 + required: + - domain + - organization_id + CreateOrganizationApiKeyDto: + type: object + properties: + name: + type: string + description: The name for the API key. + example: Production API Key + permissions: + description: The permission slugs to assign to the API key. + example: + - posts:read + - posts:write + type: array + items: type: string - - name: before - required: false - in: query + required: + - name + OrganizationDomainDataDto: + type: object + properties: + domain: + type: string + description: The domain value. + example: foo-corp.com + state: + type: string + enum: + - pending + - verified + description: The verification state of the domain. + example: verified + required: + - domain + - state + OrganizationDto: + type: object + properties: + name: + type: string + description: The name of the organization. + example: Foo Corp + allow_profiles_outside_organization: + type: boolean 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. - schema: - example: obj_1234567890 + Whether the organization allows profiles from outside the + organization to sign in. + example: false + domains: + description: >- + The domains associated with the organization. Deprecated in favor of + `domain_data`. + example: + - example.com + type: array + items: type: string - - name: after - required: false - in: query + domain_data: + description: >- + The domains associated with the organization, including verification + state. + type: array + items: + $ref: '#/components/schemas/OrganizationDomainDataDto' + metadata: + type: + - object + - 'null' + additionalProperties: &ref_2 + type: string + maxLength: 600 + maxProperties: 50 + example: &ref_3 + tier: diamond + description: >- + Object containing [metadata](/authkit/metadata) key/value pairs + associated with the Organization. + propertyNames: + maxLength: 40 + external_id: + type: + - string + - 'null' + maxLength: 128 + example: ext_12345 + description: An external identifier for the Organization. + required: + - name + UpdateOrganizationDto: + type: object + properties: + name: + type: string + description: The name of the organization. + example: Foo Corp + allow_profiles_outside_organization: + type: boolean + description: >- + Whether the organization allows profiles from outside the + organization to sign in. + example: false + domains: 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. - schema: - example: obj_1234567890 + The domains associated with the organization. Deprecated in favor of + `domain_data`. + example: + - foo-corp.com + deprecated: true + type: array + items: type: string - - name: limit - required: false - in: query + domain_data: + description: >- + The domains associated with the organization, including verification + state. + type: array + items: + $ref: '#/components/schemas/OrganizationDomainDataDto' + stripe_customer_id: + type: string + description: The Stripe customer ID associated with the organization. + example: cus_R9qWAGMQ6nGE7V + metadata: + type: + - object + - 'null' + additionalProperties: *ref_2 + maxProperties: 50 + example: *ref_3 + description: >- + Object containing [metadata](/authkit/metadata) key/value pairs + associated with the Organization. + propertyNames: + maxLength: 40 + external_id: + type: + - string + - 'null' + maxLength: 128 + example: 2fe01467-f7ea-4dd2-8b79-c2b4f56d0191 + description: An external identifier for the Organization. + SsoIntentOptions: + type: object + properties: + bookmark_slug: + type: string + description: The bookmark slug to use for SSO. + example: chatgpt + provider_type: + type: string + description: The SSO provider type to configure. + example: GoogleSAML + const: GoogleSAML + IntentOptions: + type: object + properties: + sso: + description: SSO-specific options for the Admin Portal. + $ref: '#/components/schemas/SsoIntentOptions' + required: + - sso + GenerateLinkDto: + type: object + properties: + return_url: + type: string + description: >- + The URL to go to when an admin clicks on your logo in the Admin + Portal. If not specified, the return URL configured on the + [Redirects](https://dashboard.workos.com/redirects) page will be + used. + example: https://example.com/admin-portal/return + success_url: + type: string + description: >- + The URL to redirect the admin to when they finish setup. If not + specified, the success URL configured on the + [Redirects](https://dashboard.workos.com/redirects) page will be + used. + example: https://example.com/admin-portal/success + organization: + type: string + description: An [Organization](/reference/organization) identifier. + example: org_01EHZNVPK3SFK441A1RGBFSHRT + intent: + type: string + description: |2- + + The intent of the Admin Portal. + - `sso` - Launch Admin Portal for creating SSO connections + - `dsync` - Launch Admin Portal for creating Directory Sync connections + - `audit_logs` - Launch Admin Portal for viewing Audit Logs + - `log_streams` - Launch Admin Portal for creating Log Streams + - `domain_verification` - Launch Admin Portal for Domain Verification + - `certificate_renewal` - Launch Admin Portal for renewing SAML Certificates + - `bring_your_own_key` - Launch Admin Portal for configuring Bring Your Own Key + example: sso + enum: + - sso + - dsync + - audit_logs + - log_streams + - domain_verification + - certificate_renewal + - bring_your_own_key + intent_options: + description: Options to configure the Admin Portal based on the intent. + $ref: '#/components/schemas/IntentOptions' + required: + - organization + CreateRedirectUriDto: + type: object + properties: + uri: + type: string + description: The redirect URI to create. + example: https://example.com/callback + required: + - uri + EnrollUserlandUserAuthenticationFactorDto: + type: object + properties: + type: + type: string + description: The type of the factor to enroll. + example: totp + const: totp + totp_issuer: + type: string + description: >- + Your application or company name displayed in the user's + authenticator app. + example: WorkOS + totp_user: + type: string + description: The user's account name displayed in their authenticator app. + example: user@example.com + totp_secret: + type: string + description: >- + The Base32-encoded shared secret for TOTP factors. This can be + provided when creating the auth factor, otherwise it will be + generated. The algorithm used to derive TOTP codes is SHA-1, the + code length is 6 digits, and the timestep is 30 seconds – the secret + must be compatible with these parameters. + example: JBSWY3DPEHPK3PXP + required: + - type + CreateUserlandMagicCodeAndReturnDto: + type: object + properties: + email: + type: string + description: The email address to send the magic code to. + example: marcelina.davis@example.com + invitation_token: + type: string + description: The invitation token to associate with this magic code. + example: Z1Y2X3W4V5U6T7S8R9Q0P1O2N3 + required: + - email + CreateUserlandUserInviteOptionsDto: + type: object + properties: + email: + type: string + description: The email address of the recipient. + example: marcelina.davis@example.com + organization_id: + type: string + description: >- + The ID of the [organization](/reference/organization) that the + recipient will join. + example: org_01E4ZCR3C56J083X43JQXF3JK5 + role_slug: + type: string + description: >- + The [role](/authkit/roles) that the recipient will receive when they + join the organization in the invitation. + example: admin + expires_in_days: + type: number + description: >- + How many days the invitations will be valid for. Must be between 1 + and 30 days. Defaults to 7 days if not specified. + example: 7 + inviter_user_id: + type: string + description: >- + The ID of the [user](/reference/authkit/user) who invites the + recipient. The invitation email will mention the name of this user. + example: user_01HYGBX8ZGD19949T3BM4FW1C3 + locale: + type: string + enum: + - af + - am + - ar + - bg + - bn + - bs + - ca + - cs + - da + - de + - de-DE + - el + - en + - en-AU + - en-CA + - en-GB + - en-US + - es + - es-419 + - es-ES + - es-US + - et + - fa + - fi + - fil + - fr + - fr-BE + - fr-CA + - fr-FR + - fy + - gl + - gu + - ha + - he + - hi + - hr + - hu + - hy + - id + - is + - it + - it-IT + - ja + - jv + - ka + - kk + - km + - kn + - ko + - lt + - lv + - mk + - ml + - mn + - mr + - ms + - my + - nb + - ne + - nl + - nl-BE + - nl-NL + - nn + - 'no' + - pa + - pl + - pt + - pt-BR + - pt-PT + - ro + - ru + - sk + - sl + - sq + - sr + - sv + - sw + - ta + - te + - th + - tr + - uk + - ur + - uz + - vi + - zh + - zh-CN + - zh-HK + - zh-TW + - zu description: >- - Upper limit on the number of objects to return, between `1` and - `100`. - schema: - minimum: 1 - maximum: 100 - default: 10 - example: 10 - type: number - - name: order - required: false - in: query - description: Order the results by the creation time. - schema: - default: desc - example: desc - enum: - - normal - - desc - - asc - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - type: object - properties: - object: - type: string - description: Distinguishes the authentication factor object. - const: authentication_factor - id: - type: string - description: The unique ID of the factor. - example: auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ - type: - type: string - enum: - - generic_otp - - sms - - totp - - webauthn - description: The type of the factor to enroll. - example: totp - user_id: - type: string - description: The ID of the [user](/reference/authkit/user). - example: user_01E4ZCR3C56J083X43JQXF3JK5 - sms: - type: object - properties: - phone_number: - type: string - description: >- - The user's phone number for SMS-based - authentication. - example: '+15005550006' - required: - - phone_number - description: SMS-based authentication factor details. - totp: - oneOf: - - type: object - properties: - issuer: - type: string - description: >- - Your application or company name displayed - in the user's authenticator app. Defaults to - your WorkOS team name. - example: WorkOS - user: - type: string - description: >- - The user's account name displayed in their - authenticator app. Defaults to the user's - email. - example: user@example.com - secret: - type: string - description: >- - TOTP secret that can be manually entered - into some authenticator apps in place of - scanning a QR code. - example: JBSWY3DPEHPK3PXP - qr_code: - type: string - description: >- - Base64 encoded image containing scannable QR - code. - example: >- - data:image/png;base64,iVBORw0KGgoAAAANSUhEUg... - uri: - type: string - description: >- - The `otpauth` URI that is encoded by the - provided `qr_code`. - example: >- - otpauth://totp/WorkOS:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=WorkOS - required: - - issuer - - user - - secret - - qr_code - - uri - additionalProperties: false - - type: object - properties: - issuer: - type: string - description: >- - Your application or company name displayed - in the user's authenticator app. Defaults to - your WorkOS team name. - example: WorkOS - user: - type: string - description: >- - The user's account name displayed in their - authenticator app. Defaults to the user's - email. - example: user@example.com - required: - - issuer - - user - additionalProperties: false - description: TOTP-based authentication factor details. - 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 - - type - - created_at - - updated_at - 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: auth_factor_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: auth_factor_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: >- - Pagination cursors for navigating between pages of - results. - required: - - object - - data - - list_metadata - '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 - tags: - - user-management.multi-factor-authentication - /webhook_endpoints: - get: - operationId: WebhookEndpointsController_list - summary: List Webhook Endpoints - description: Get a list of all of your existing webhook endpoints. - parameters: - - name: before - required: false - in: query + The locale to use when rendering the invitation email. See + [supported locales](/authkit/hosted-ui/localization). + example: en + required: + - email + ResendUserlandUserInviteOptionsDto: + type: object + properties: + locale: + type: string + enum: + - af + - am + - ar + - bg + - bn + - bs + - ca + - cs + - da + - de + - de-DE + - el + - en + - en-AU + - en-CA + - en-GB + - en-US + - es + - es-419 + - es-ES + - es-US + - et + - fa + - fi + - fil + - fr + - fr-BE + - fr-CA + - fr-FR + - fy + - gl + - gu + - ha + - he + - hi + - hr + - hu + - hy + - id + - is + - it + - it-IT + - ja + - jv + - ka + - kk + - km + - kn + - ko + - lt + - lv + - mk + - ml + - mn + - mr + - ms + - my + - nb + - ne + - nl + - nl-BE + - nl-NL + - nn + - 'no' + - pa + - pl + - pt + - pt-BR + - pt-PT + - ro + - ru + - sk + - sl + - sq + - sr + - sv + - sw + - ta + - te + - th + - tr + - uk + - ur + - uz + - vi + - zh + - zh-CN + - zh-HK + - zh-TW + - zu 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 + The locale to use when rendering the invitation email. See + [supported locales](/authkit/hosted-ui/localization). + example: en + CreateUserlandUserOrganizationMembershipDto: + type: object + properties: + user_id: + type: string + description: The ID of the [user](/reference/authkit/user). + example: user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E + organization_id: + type: string + description: >- + The ID of the [organization](/reference/organization) which the user + belongs to. + example: org_01E4ZCR3C56J083X43JQXF3JK5 + role_slug: + type: string + description: >- + A single role identifier. Defaults to `member` or the explicit + default role. Mutually exclusive with `role_slugs`. + example: admin + x-mutually-exclusive-with: + - role_slugs + role_slugs: + description: >- + An array of role identifiers. Limited to one role when Multiple + Roles is disabled. Mutually exclusive with `role_slug`. + example: + - admin + x-mutually-exclusive-with: + - role_slug + type: array + items: type: string - - name: after - required: false - in: query + required: + - user_id + - organization_id + UpdateUserlandUserOrganizationMembershipDto: + type: object + properties: + role_slug: + type: string 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 + A single role identifier. Defaults to `member` or the explicit + default role. Mutually exclusive with `role_slugs`. + example: admin + x-mutually-exclusive-with: + - role_slugs + role_slugs: + description: >- + An array of role identifiers. Limited to one role when Multiple + Roles is disabled. Mutually exclusive with `role_slug`. + example: + - admin + x-mutually-exclusive-with: + - role_slug + type: array + items: type: string - - name: limit - required: false - in: query + CreateUserlandUserDto: + type: object + properties: + email: + type: string + description: The email address of the user. + example: marcelina.davis@example.com + password: + type: + - string + - 'null' description: >- - Upper limit on the number of objects to return, between `1` and - `100`. - schema: - minimum: 1 - maximum: 100 - default: 10 - example: 10 - type: number - - name: order - required: false - in: query + The password to set for the user. Mutually exclusive with + `password_hash` and `password_hash_type`. + example: strong_password_123! + x-mutually-exclusive-with: + - password_hash + - password_hash_type + password_hash: + type: string + description: >- + The hashed password to set for the user. Mutually exclusive with + `password`. + example: $2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy + x-mutually-exclusive-with: + - password + password_hash_type: + type: string + enum: &ref_4 + - bcrypt + - firebase-scrypt + - ssha + - scrypt + - pbkdf2 + - argon2 + description: >- + The algorithm originally used to hash the password, used when + providing a `password_hash`. + example: bcrypt + first_name: + type: + - string + - 'null' + description: The first name of the user. + example: Marcelina + last_name: + type: + - string + - 'null' + description: The last name of the user. + example: Davis + email_verified: + type: + - boolean + - 'null' + description: Whether the user's email has been verified. + example: true + metadata: + type: + - object + - 'null' + additionalProperties: *ref_2 + maxProperties: 50 + example: &ref_5 + timezone: America/New_York + description: Object containing metadata key/value pairs associated with the user. + propertyNames: + maxLength: 40 + external_id: + type: + - string + - 'null' + maxLength: 128 + description: The external ID of the user. + example: f1ffa2b2-c20b-4d39-be5c-212726e11222 + required: + - email + UpdateUserlandUserDto: + type: object + properties: + email: + type: string + description: The email address of the user. + example: marcelina.davis@example.com + first_name: + type: string + description: The first name of the user. + example: Marcelina + last_name: + type: string + description: The last name of the user. + example: Davis + email_verified: + type: boolean + description: Whether the user's email has been verified. + example: true + password: + type: string + description: The password to set for the user. + example: strong_password_123! + password_hash: + type: string + description: >- + The hashed password to set for the user. Mutually exclusive with + `password`. + example: $2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy + x-mutually-exclusive-with: + - password + password_hash_type: + type: string + enum: *ref_4 + description: >- + The algorithm originally used to hash the password, used when + providing a `password_hash`. + example: bcrypt + metadata: + type: + - object + - 'null' + additionalProperties: *ref_2 + maxProperties: 50 + example: *ref_5 + description: Object containing metadata key/value pairs associated with the user. + propertyNames: + maxLength: 40 + external_id: + type: + - string + - 'null' + maxLength: 128 + description: The external ID of the user. + example: f1ffa2b2-c20b-4d39-be5c-212726e11222 + locale: + type: + - string + - 'null' + description: The user's preferred locale. + example: en-US + VerifyEmailAddressDto: + type: object + properties: + code: + type: string + description: The one-time email verification code. + example: '123456' + required: + - code + CreatePasswordResetTokenDto: + type: object + properties: + email: + type: string + description: The email address of the user requesting a password reset. + example: marcelina.davis@example.com + required: + - email + CreatePasswordResetDto: + type: object + properties: + token: + type: string + description: The password reset token. + example: Z1Y2X3W4V5U6T7S8R9Q0P1O2N3 + new_password: + type: string + description: The new password to set for the user. + example: strong_password_123! + required: + - token + - new_password + UserlandRevokeSessionDto: + type: object + properties: + session_id: + type: string 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: - default: desc - example: desc - enum: - - normal - - desc - - asc + The ID of the session to revoke. This can be extracted from the + `sid` claim of the access token. + example: session_01H93ZY4F80QPBEZ1R5B2SHQG8 + return_to: + type: string + description: The URL to redirect the user to after session revocation. + example: https://example.com + required: + - session_id + CreateWebhookEndpointDto: + type: object + properties: + endpoint_url: + type: string + description: The HTTPS URL where webhooks will be sent. + example: https://example.com/webhooks + events: + description: The events that the Webhook Endpoint is subscribed to. + example: + - user.created + - dsync.user.created + type: array + items: type: string - responses: - '200': - description: List of webhook endpoints. - content: - application/json: - schema: - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - type: object - properties: - object: - type: string - description: Distinguishes the Webhook Endpoint object. - const: webhook_endpoint - id: - type: string - description: Unique identifier of the Webhook Endpoint. - example: we_0123456789 - endpoint_url: - type: string - description: The URL to which webhooks are sent. - example: https://example.com/webhooks - secret: - type: string - description: The secret used to sign webhook payloads. - example: whsec_0FWAiVGkEfGBqqsJH4aNAGBJ4 - status: - type: string - enum: - - enabled - - disabled - description: Whether the Webhook Endpoint is enabled or disabled. - example: enabled - events: - type: array - items: - type: string - description: >- - The events that the Webhook Endpoint is subscribed - to. - example: - - user.created - - dsync.user.created - 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 - - endpoint_url - - secret - - status - - events - - created_at - - updated_at - 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: we_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: we_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: >- - Pagination cursors for navigating between pages of - results. - required: - - object - - data - - list_metadata - tags: - - webhooks - post: - operationId: WebhookEndpointsController_create - summary: Create a Webhook Endpoint - description: Create a new webhook endpoint to receive event notifications. - parameters: [] - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreateWebhookEndpointDto' - responses: - '201': - description: Webhook endpoint created successfully. - content: - application/json: - schema: - type: object - properties: - object: - type: string - description: Distinguishes the Webhook Endpoint object. - const: webhook_endpoint - id: - type: string - description: Unique identifier of the Webhook Endpoint. - example: we_0123456789 - endpoint_url: - type: string - description: The URL to which webhooks are sent. - example: https://example.com/webhooks - secret: - type: string - description: The secret used to sign webhook payloads. - example: whsec_0FWAiVGkEfGBqqsJH4aNAGBJ4 - status: - type: string - enum: - - enabled - - disabled - description: Whether the Webhook Endpoint is enabled or disabled. - example: enabled - events: - type: array - items: - type: string - description: The events that the Webhook Endpoint is subscribed to. - example: - - user.created - - dsync.user.created - 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 - - endpoint_url - - secret - - status - - events - - created_at - - updated_at - '409': - description: A Webhook Endpoint with the same endpoint URL already exists. - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: duplicate_endpoint - const: duplicate_endpoint - 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: - oneOf: - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_url - const: invalid_url - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_request_parameters - const: invalid_request_parameters - message: - type: string - description: A human-readable description of the error. - example: Validation failed. - errors: - type: array - items: - type: object - properties: - code: - type: string - description: The validation error code. - example: unknown_event_type - message: - type: string - description: >- - A human-readable description of the validation - error. - example: Invalid enum value. - required: - - code - - message - description: The list of validation errors. - required: - - code - - message - - errors - tags: - - webhooks - /webhook_endpoints/{id}: - delete: - operationId: WebhookEndpointsController_delete - summary: Delete a Webhook Endpoint - description: Delete an existing webhook endpoint. - parameters: - - name: id - required: true - in: path - description: Unique identifier of the Webhook Endpoint. - schema: + required: + - endpoint_url + - events + WidgetSessionTokenDto: + type: object + properties: + organization_id: + type: string + description: The ID of the organization to scope the widget session to. + example: org_01EHZNVPK3SFK441A1RGBFSHRT + user_id: + type: string + description: The ID of the user to issue the widget session token for. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + scopes: + type: array + description: The scopes to grant the widget session. + items: type: string - example: we_0123456789 - responses: - '204': - description: Webhook endpoint deleted successfully. - '404': - description: Webhook endpoint not found. - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: entity_not_found - const: entity_not_found - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - tags: - - webhooks - /widgets/token: - post: - operationId: WidgetsPublicController_issueWidgetSessionToken - summary: Generate a widget token - description: >- - Generate a widget token scoped to an organization and user with the - specified scopes. - parameters: [] - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/WidgetSessionTokenDto' - responses: - '201': - description: Created - content: - application/json: - schema: - type: object - properties: - token: - type: string - description: The widget session token. - example: eyJhbGciOiJSUzI1NiIsImtpZCI6InNlc3Npb24... - required: - - token - '400': - description: Bad Request - content: - application/json: - schema: - oneOf: - - type: object - properties: - message: - type: string - description: A human-readable description of the error. - example: >- - Organization not found: - 'org_01EHQMYV6MBK39QC5PZXHY59C3'. - required: - - message - - type: object - properties: - message: - type: array - items: - type: string - description: A list of validation error messages. - example: - - organization_id must be a string - error: - type: string - description: The error type. - example: Bad Request - required: - - message - - error - '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 - tags: - - widgets -info: - title: WorkOS - description: WorkOS REST API - version: '1.0' - contact: - name: WorkOS - url: https://workos.com - email: support@workos.com -tags: - - name: admin-portal - description: Endpoints for the Admin Portal API. - - name: api_keys - description: Manage API keys for environments. - - name: application.client-secrets - description: Manage client secrets for Connect Applications. - - name: applications - description: Manage Connect Applications. - - name: audit-logs - description: Create and query audit log events. - - name: authorization - description: Authorization and access control. - - name: connections - description: Manage SSO connections. - - name: directories - description: Manage directories. - - name: directory-groups - description: Manage directory groups. - - name: directory-users - description: Manage directory users. - - name: events - description: Query events and event streams. - - name: feature-flags - description: Manage feature flags. - - name: feature-flags.targets - description: Manage feature flag targets. - - name: multi-factor-auth - description: Multi-factor authentication factor management. - - name: multi-factor-auth.challenges - description: Multi-factor authentication challenge verification. - - name: organizations - description: Manage organizations. - - name: organizations.api_keys - description: Manage organization-scoped API keys. - - name: organizations.feature-flags - description: Manage organization-scoped feature flags. - - name: permissions - description: Manage permissions. - - name: pipes - description: Data integration endpoints. - - name: radar - description: Radar fraud detection. - - name: sso - description: Single Sign-On endpoints. - - name: user-management.authentication - description: User authentication endpoints. - - name: user-management.cors-origins - description: Manage CORS origins for user management. - - name: user-management.data-providers - description: Manage data providers. - - name: user-management.invitations - description: Manage user invitations. - - name: user-management.jwt-template - description: Manage JWT templates. - - name: user-management.magic-auth - description: Magic auth endpoints. - - name: user-management.multi-factor-authentication - description: Multi-factor authentication endpoints. - - name: user-management.organization-membership - description: Manage user organization memberships. - - name: user-management.redirect-uris - description: Manage redirect URIs. - - name: user-management.session-tokens - description: Session token verification keys. - - name: user-management.users - description: Manage users. - - name: user-management.users.authorized-applications - description: Manage authorized applications for users. - - name: user-management.users.feature-flags - description: Manage user-scoped feature flags. - - name: webhooks - description: Manage webhooks. - - name: widgets - description: Widget endpoints. - - name: workos-connect - description: >- - A unified interface that simplifies authentication and authorization - across customers, partners, and external SaaS tools. -servers: - - url: https://api.workos.com - description: Production - - url: https://api.workos-test.com - description: Staging -components: - 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. - schemas: - UserObject: + enum: + - widgets:users-table:manage + - widgets:domain-verification:manage + - widgets:sso:manage + - widgets:api-keys:manage + - widgets:dsync:manage + - widgets:audit-log-streaming:manage + example: + - widgets:users-table:manage + required: + - organization_id + TokenQueryDto: + type: object + properties: + client_id: + type: string + description: The client ID of the WorkOS environment. + example: client_01HZBC6N1EB1ZY7KG32X + client_secret: + type: string + description: The client secret of the WorkOS environment. + example: sk_example_123456789 + code: + type: string + description: The authorization code received from the authorization callback. + example: authorization_code_value + grant_type: + type: string + description: The grant type for the token request. + example: authorization_code + const: authorization_code + required: + - client_id + - client_secret + - code + - grant_type + ExternalAuthCompleteResponse: + type: object + properties: + redirect_uri: + type: string + description: URI to redirect the user back to AuthKit to complete the OAuth flow. + example: >- + https://your-authkit-domain.workos.com/oauth/authorize/complete?state=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdGF0ZSI6InJhbmRvbV9zdGF0ZV9zdHJpbmciLCJpYXQiOjE3NDI2MDQ4NTN9.abc123def456ghi789 + required: + - redirect_uri + ApiKey: + type: object + properties: + object: + type: string + description: Distinguishes the API Key object. + const: api_key + id: + type: string + description: Unique identifier of the API Key. + example: api_key_01EHZNVPK3SFK441A1RGBFSHRT + owner: + type: object + properties: + type: + type: string + description: The type of the API Key owner. + example: organization + const: organization + id: + type: string + description: Unique identifier of the API Key owner. + example: org_01EHZNVPK3SFK441A1RGBFSHRT + required: + - type + - id + description: The entity that owns the API Key. + name: + type: string + description: A descriptive name for the API Key. + example: Production API Key + obfuscated_value: + type: string + description: An obfuscated representation of the API Key value. + example: sk_...3456 + last_used_at: + type: + - string + - 'null' + description: Timestamp of when the API Key was last used. + example: null + permissions: + type: array + items: + type: string + description: The permission slugs assigned to the API Key. + 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: + - object + - id + - owner + - name + - obfuscated_value + - last_used_at + - permissions + - created_at + - updated_at + description: The API Key object if the value is valid, or `null` if invalid. + ApiKeyValidationResponse: + type: object + properties: + api_key: + oneOf: + - $ref: '#/components/schemas/ApiKey' + - type: 'null' + required: + - api_key + ConnectApplication: + allOf: + - type: object + properties: + object: + type: string + description: Distinguishes the connect application object. + example: connect_application + const: connect_application + id: + type: string + description: The unique ID of the connect application. + example: conn_app_01HXYZ123456789ABCDEFGHIJ + client_id: + type: string + description: The client ID of the connect application. + example: client_01HXYZ123456789ABCDEFGHIJ + description: + type: + - string + - 'null' + description: A description of the connect application. + example: An application for managing user access + name: + type: string + description: The name of the connect application. + example: My Application + scopes: + type: array + items: + type: string + description: The scopes available for this application. + example: + - openid + - profile + - email + 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 + - client_id + - description + - name + - scopes + - created_at + - updated_at + - oneOf: + - allOf: + - type: object + properties: + application_type: + type: string + description: The type of the application. + const: oauth + redirect_uris: + type: array + items: + type: object + properties: + uri: + type: string + format: uri + description: The redirect URI for the application. + example: https://example.com/callback + default: + type: boolean + description: Whether this is the default redirect URI. + example: true + required: + - uri + - default + description: The redirect URIs configured for this application. + uses_pkce: + type: boolean + description: Whether the application uses PKCE for authorization. + example: true + required: + - application_type + - redirect_uris + - uses_pkce + - oneOf: + - type: object + properties: + is_first_party: + type: boolean + description: >- + Whether the application is a first-party + application. + example: true + const: true + required: + - is_first_party + - type: object + properties: + is_first_party: + type: boolean + description: >- + Whether the application is a first-party + application. + example: false + const: false + was_dynamically_registered: + type: boolean + description: Whether the application was dynamically registered. + example: false + const: false + organization_id: + type: string + description: >- + The ID of the organization the application belongs + to. + example: org_01EHZNVPK3SFK441A1RGBFSHRT + required: + - is_first_party + - was_dynamically_registered + - organization_id + - type: object + properties: + is_first_party: + type: boolean + description: >- + Whether the application is a first-party + application. + example: false + const: false + was_dynamically_registered: + type: boolean + description: Whether the application was dynamically registered. + example: true + const: true + required: + - is_first_party + - was_dynamically_registered + - type: object + properties: + application_type: + type: string + description: The type of the application. + example: m2m + const: m2m + organization_id: + type: string + description: The ID of the organization the application belongs to. + example: org_01EHZNVPK3SFK441A1RGBFSHRT + required: + - application_type + - organization_id + ConnectApplicationList: + type: object + properties: + object: + type: string + description: Indicates this is a list response. + const: list + data: + type: array + items: + $ref: '#/components/schemas/ConnectApplication' + 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: conn_app_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: conn_app_01HXYZ987654321KJIHGFEDCBA + required: + - before + - after + description: Pagination cursors for navigating between pages of results. + required: + - object + - data + - list_metadata + AuthorizedConnectApplicationList: + type: object + properties: + object: + type: string + description: Indicates this is a list response. + const: list + data: + type: array + items: + type: object + properties: + object: + type: string + description: Distinguishes the authorized connect application object. + const: authorized_connect_application + id: + type: string + description: The unique ID of the authorized connect application. + example: aca_01HXYZ123456789ABCDEFGHIJ + granted_scopes: + type: array + items: + type: string + description: The scopes granted by the user to the application. + example: + - openid + - profile + - email + application: + $ref: '#/components/schemas/ConnectApplication' + required: + - object + - id + - granted_scopes + - application + 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: aca_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: aca_01HXYZ987654321KJIHGFEDCBA + required: + - before + - after + description: Pagination cursors for navigating between pages of results. + required: + - object + - data + - list_metadata + NewConnectApplicationSecret: + type: object + properties: + object: + type: string + description: Distinguishes the connect application secret object. + const: connect_application_secret + id: + type: string + description: The unique ID of the client secret. + example: secret_01J9Q2Z3X4Y5W6V7U8T9S0R1Q + secret_hint: + type: string + description: A hint showing the last few characters of the secret value. + example: abc123 + last_used_at: + type: + - string + - 'null' + description: >- + The timestamp when the client secret was last used, or null if never + used. + example: null + 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' + secret: + type: string + description: >- + The plaintext secret value. Only returned at creation time and + cannot be retrieved later. + example: abc123def456ghi789jkl012mno345pqr678stu901vwx234yz + required: + - object + - id + - secret_hint + - last_used_at + - created_at + - updated_at + - secret + AuditLogEventCreateResponse: + type: object + properties: + success: + type: boolean + description: Whether the Audit Log event was created successfully. + example: true + required: + - success + AuditLogExportJson: + type: object + properties: + object: + type: string + description: Distinguishes the Audit Log Export object. + example: audit_log_export + const: audit_log_export + id: + type: string + description: The unique ID of the Audit Log Export. + example: audit_log_export_01GBZK5MP7TD1YCFQHFR22180V + state: + type: string + enum: + - pending + - ready + - error + description: 'The state of the export. Possible values: pending, ready, error.' + example: ready + url: + type: + - string + - 'null' + description: >- + A URL to the CSV file. Only defined when the Audit Log Export is + ready. + example: https://exports.audit-logs.com/audit-log-exports/export.csv + 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 + - state + - created_at + - updated_at + AuditLogsRetentionJson: + type: object + properties: + retention_period_in_days: + type: + - number + - 'null' + description: >- + The number of days Audit Log events will be retained before being + permanently deleted. Valid values are 30 and 365. + example: 30 + required: + - retention_period_in_days + AuditLogSchemaJson: + type: object + properties: + object: + type: string + description: Distinguishes the Audit Log Schema object. + example: audit_log_schema + const: audit_log_schema + version: + type: number + description: The version of the schema. + example: 1 + actor: + type: object + properties: + metadata: + type: object + additionalProperties: {} + description: The JSON Schema definition for actor metadata. + required: + - metadata + description: The metadata schema for the actor. + example: + metadata: + type: object + properties: + role: + type: string + targets: + type: array + items: + type: object + properties: + type: + type: string + description: The type of the target resource. + example: invoice + metadata: + type: object + additionalProperties: {} + description: Additional data associated with the event or entity. + example: + type: object + properties: + cost: + type: number + required: + - type + description: The list of targets for the schema. + example: + - type: invoice + metadata: + type: object + properties: + cost: + type: number + metadata: + type: object + additionalProperties: {} + description: Additional data associated with the event or entity. + example: + type: object + properties: + transactionId: + type: string + created_at: + format: date-time + type: string + description: The timestamp when the Audit Log Schema was created. + example: '2026-01-15T12:00:00.000Z' + required: + - object + - version + - targets + - created_at + description: The schema associated with the action. + AuditLogActionJson: + type: object + properties: + object: + type: string + description: Distinguishes the Audit Log Action object. + example: audit_log_action + const: audit_log_action + name: + type: string + description: Identifier of what action was taken. + example: user.viewed_invoice + schema: + $ref: '#/components/schemas/AuditLogSchemaJson' + 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 + - name + - schema + - created_at + - updated_at + AuthenticationChallenge: type: object properties: + object: + type: string + description: Distinguishes the authentication challenge object. + const: authentication_challenge id: + type: string + description: The unique ID of the authentication challenge. + example: auth_challenge_01FVYZ5QM8N98T9ME5BCB2BBMJ + expires_at: + format: date-time type: string description: >- - Your application's user identifier, which will be stored as an - [`external_id`](/authkit/metadata/external-identifiers). Used for - upserting and deduplication. - example: user_12345 - email: + The timestamp when the challenge will expire. Does not apply to TOTP + factors. + example: '2026-01-15T12:00:00.000Z' + code: type: string - description: The user's email address. - example: marcelina.davis@example.com - first_name: + description: The one-time code for the challenge. + example: '123456' + authentication_factor_id: type: string - description: The user's first name. - example: Marcelina - last_name: + description: The unique ID of the authentication factor the challenge belongs to. + example: auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ + created_at: + format: date-time type: string - description: The user's last name. - example: Davis - metadata: - type: object - description: A set of key-value pairs to attach to the user. - additionalProperties: - type: string - maxLength: 600 - maxProperties: 50 - example: - department: Engineering - role: Developer - propertyNames: - maxLength: 40 + 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 - - email - UserConsentOption: + - authentication_factor_id + - created_at + - updated_at + description: The authentication challenge object. + AuthenticationChallengeVerifyResponse: type: object properties: - claim: + challenge: + $ref: '#/components/schemas/AuthenticationChallenge' + valid: + type: boolean + description: Whether the code was valid. + example: true + required: + - challenge + - valid + AuthenticationFactor: + type: object + properties: + object: type: string - description: The claim name for this consent option. - example: tos_accepted + description: Distinguishes the authentication factor object. + const: authentication_factor + id: + type: string + description: The unique ID of the factor. + example: auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ type: type: string - description: The type of consent option. - const: enum - label: + enum: + - generic_otp + - sms + - totp + - webauthn + description: The type of the factor to enroll. + example: totp + user_id: type: string - description: A human-readable label for this consent option. - example: Terms of Service - choices: - type: array - description: The available choices for this consent option. - items: - type: object - properties: - value: - type: string - description: The value of this choice. - example: accepted - label: - type: string - description: A human-readable label for this choice. - example: I accept the Terms of Service - example: - - value: accepted - label: I accept the Terms of Service + description: The ID of the [user](/reference/authkit/user). + example: user_01E4ZCR3C56J083X43JQXF3JK5 + sms: + type: object + properties: + phone_number: + type: string + description: The user's phone number for SMS-based authentication. + example: '+15005550006' + required: + - phone_number + description: SMS-based authentication factor details. + totp: + oneOf: + - type: object + properties: + issuer: + type: string + description: >- + Your application or company name displayed in the user's + authenticator app. Defaults to your WorkOS team name. + example: WorkOS + user: + type: string + description: >- + The user's account name displayed in their authenticator + app. Defaults to the user's email. + example: user@example.com + secret: + type: string + description: >- + TOTP secret that can be manually entered into some + authenticator apps in place of scanning a QR code. + example: JBSWY3DPEHPK3PXP + qr_code: + type: string + description: Base64 encoded image containing scannable QR code. + example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUg... + uri: + type: string + description: The `otpauth` URI that is encoded by the provided `qr_code`. + example: >- + otpauth://totp/WorkOS:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=WorkOS + required: + - issuer + - user + - secret + - qr_code + - uri + additionalProperties: false + - type: object + properties: + issuer: + type: string + description: >- + Your application or company name displayed in the user's + authenticator app. Defaults to your WorkOS team name. + example: WorkOS + user: + type: string + description: >- + The user's account name displayed in their authenticator + app. Defaults to the user's email. + example: user@example.com + required: + - issuer + - user + additionalProperties: false + description: TOTP-based authentication factor details. + 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 + - type + - created_at + - updated_at + description: >- + The [authentication + factor](/reference/authkit/mfa/authentication-factor) object that + represents the additional authentication method used on top of the + existing authentication strategy. + AuthorizationCheck: + type: object + properties: + authorized: + type: boolean + description: >- + Whether the organization membership has the specified permission on + the resource. + example: true + required: + - authorized + AuthorizationResource: + type: object + properties: + object: + type: string + description: Distinguishes the Resource object. + const: authorization_resource + name: + type: string + description: A human-readable name for the Resource. + example: Website Redesign + description: + type: + - string + - 'null' + description: An optional description of the Resource. + example: Company website redesign project + organization_id: + type: string + description: The ID of the organization that owns the resource. + example: org_01EHZNVPK3SFK441A1RGBFSHRT + parent_resource_id: + type: + - string + - 'null' + description: The ID of the parent resource, if this resource is nested. + example: authz_resource_01HXYZ123456789ABCDEFGHIJ + id: + type: string + description: The unique ID of the Resource. + example: authz_resource_01HXYZ123456789ABCDEFGH + external_id: + type: string + description: An identifier you provide to reference the resource in your system. + example: proj-456 + resource_type_slug: + type: string + description: The slug of the resource type this resource belongs to. + example: project + 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: - - claim - - type - - label - - choices - UserManagementLoginRequest: + - object + - name + - description + - organization_id + - parent_resource_id + - id + - external_id + - resource_type_slug + - created_at + - updated_at + AuthorizationResourceList: type: object properties: - external_auth_id: + object: type: string - description: Identifier provided when AuthKit redirected to your login page. - example: ext_auth_01HXYZ123456789ABCDEFGHIJ - user: - description: The user to create or update in AuthKit. - $ref: '#/components/schemas/UserObject' - user_consent_options: - description: >- - Array of [User Consent - Options](/reference/workos-connect/standalone/user-consent-options) - to store with the session. + description: Indicates this is a list response. + const: list + data: type: array items: - $ref: '#/components/schemas/UserConsentOption' + $ref: '#/components/schemas/AuthorizationResource' + 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: authz_resource_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: authz_resource_01HXYZ987654321KJIHGFEDCBA + required: + - before + - after + description: Pagination cursors for navigating between pages of results. required: - - external_auth_id - - user - ValidateApiKeyDto: + - object + - data + - list_metadata + SlimRole: type: object properties: - value: + slug: type: string - description: The value for an API key. - example: sk_example_1234567890abcdef + description: The slug of the assigned role. + example: admin required: - - value - RedirectUriDto: + - slug + description: The role included in the assignment. + RoleAssignment: type: object properties: - uri: + object: type: string - description: The redirect URI. - example: https://example.com/callback - default: - type: - - boolean - - 'null' - description: Whether this is the default redirect URI. - example: true + description: Distinguishes the role assignment object. + const: role_assignment + id: + type: string + description: Unique identifier of the role assignment. + example: role_assignment_01HXYZ123456789ABCDEFGH + role: + $ref: '#/components/schemas/SlimRole' + resource: + type: object + properties: + id: + type: string + description: The unique ID of the Resource. + example: authz_resource_01HXYZ123456789ABCDEFGH + external_id: + type: string + description: >- + An identifier you provide to reference the resource in your + system. + example: proj-456 + resource_type_slug: + type: string + description: The slug of the resource type this resource belongs to. + example: project + required: + - id + - external_id + - resource_type_slug + description: The resource to which the role is assigned. + 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: - - uri - CreateOAuthApplicationDto: + - object + - id + - role + - resource + - created_at + - updated_at + RoleAssignmentList: type: object properties: - name: - type: string - description: The name of the application. - example: My Application - application_type: + object: type: string - description: The type of application to create. - const: oauth - description: - type: - - string - - 'null' - description: A description for the application. - example: An application for managing user access - scopes: - description: The OAuth scopes granted to the application. - example: &ref_0 - - openid - - profile - - email - type: - - array - - 'null' - items: - type: string - redirect_uris: - description: Redirect URIs for the application. - example: - - uri: https://example.com/callback - default: true - type: - - array - - 'null' + description: Indicates this is a list response. + const: list + data: + type: array items: - $ref: '#/components/schemas/RedirectUriDto' - uses_pkce: - type: - - boolean - - 'null' - description: Whether the application uses PKCE (Proof Key for Code Exchange). - example: true - is_first_party: - type: boolean - description: >- - Whether this is a first-party application. Third-party applications - require an organization_id. - example: true - organization_id: - type: - - string - - 'null' - description: >- - The organization ID this application belongs to. Required when - is_first_party is false. - example: org_01EHZNVPK3SFK441A1RGBFSHRT + $ref: '#/components/schemas/RoleAssignment' + 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: role_assignment_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: role_assignment_01HXYZ987654321KJIHGFEDCBA + required: + - before + - after + description: Pagination cursors for navigating between pages of results. required: - - name - - application_type - - is_first_party - CreateM2MApplicationDto: + - object + - data + - list_metadata + Role: type: object properties: - name: + slug: type: string - description: The name of the application. - example: My Application - application_type: + description: A unique slug for the role. + example: admin + object: type: string - description: The type of application to create. - const: m2m - description: - type: - - string - - 'null' - description: A description for the application. - example: An application for managing user access - scopes: - description: The OAuth scopes granted to the application. - example: *ref_0 - type: - - array - - 'null' - items: - type: string - organization_id: + description: Distinguishes the role object. + example: role + const: role + id: type: string - description: The organization ID this application belongs to. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - required: - - name - - application_type - - organization_id - UpdateOAuthApplicationDto: - type: object - properties: + description: Unique identifier of the role. + example: role_01EHQMYV6MBK39QC5PZXHY59C3 name: type: string - description: The name of the application. - example: My Application + description: A descriptive name for the role. + example: Admin description: type: - string - 'null' - description: A description for the application. - example: An application for managing user access - scopes: - description: The OAuth scopes granted to the application. - example: - - openid - - profile - - email - type: - - array - - 'null' + description: An optional description of the role. + example: Can manage all resources + type: + type: string + enum: + - EnvironmentRole + - OrganizationRole + description: Whether the role is scoped to the environment or an organization. + example: EnvironmentRole + resource_type_slug: + type: string + description: The slug of the resource type the role is scoped to. + example: default + permissions: + type: array items: type: string - redirect_uris: - description: Updated redirect URIs for the application. OAuth applications only. + description: The permission slugs assigned to the role. example: - - uri: https://example.com/callback - default: true - type: - - array - - 'null' - items: - $ref: '#/components/schemas/RedirectUriDto' - CreateApplicationSecretDto: - type: object - properties: {} - AuditLogEventActorDto: - type: object - properties: - id: - type: string - description: Actor identifier. - example: user_TF4C5938 - type: + - posts:read + - posts:write + created_at: + format: date-time type: string - description: Actor type. - example: user - name: + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + updated_at: + format: date-time type: string - description: Optional actor name. - example: Jon Smith - metadata: - type: object - description: Additional data associated with the event or entity. - example: - owner: user_01GBTCQ2 - maxProperties: 50 - additionalProperties: false - patternProperties: &ref_1 - ^[a-zA-Z0-9_-]{0,40}$: - anyOf: - - type: string - maxLength: 500 - - type: number - - type: boolean + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' required: + - slug + - object - id + - name + - description - type - AuditLogEventTargetDto: + - resource_type_slug + - permissions + - created_at + - updated_at + AuthorizationPermission: type: object properties: + object: + type: string + description: Distinguishes the Permission object. + const: permission id: type: string - description: Target identifier. - example: user_TF4C5938 - type: + description: Unique identifier of the Permission. + example: perm_01HXYZ123456789ABCDEFGHIJ + slug: type: string - description: Target type. - example: user + 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: Optional target name. - example: Jon Smith - metadata: - type: object - description: Additional data associated with the event or entity. - example: - owner: user_01GBTCQ2 - maxProperties: 50 - additionalProperties: false - patternProperties: *ref_1 + 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 - - type - AuditLogEventContextDto: + - slug + - name + - description + - system + - resource_type_slug + - created_at + - updated_at + AuthorizationPermissionList: type: object properties: - location: - type: string - description: IP Address or some other geolocation identifier. - example: 123.123.123.123 - user_agent: + object: type: string - description: User agent string. - example: Chrome/104.0.0.0 + 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: - - location - AuditLogEventDto: + - object + - data + - list_metadata + RoleList: type: object properties: - action: - type: string - description: Identifier of what happened. - example: user.signed_in - occurred_at: + object: type: string - description: ISO-8601 value of when the action occurred. - example: '2026-02-02T16:35:39.317Z' - actor: - description: The entity that performed the action. - $ref: '#/components/schemas/AuditLogEventActorDto' - targets: - description: The resources affected by the action. + example: list + const: list + data: type: array items: - $ref: '#/components/schemas/AuditLogEventTargetDto' - context: - description: Additional context about where and how the action occurred. - $ref: '#/components/schemas/AuditLogEventContextDto' - metadata: - type: object - description: Additional data associated with the event or entity. - example: - owner: user_01GBTCQ2 - maxProperties: 50 - additionalProperties: false - patternProperties: *ref_1 - version: - type: number - description: What schema version the event is associated with. - example: 1 + $ref: '#/components/schemas/Role' + description: The list of records for the current page. required: - - action - - occurred_at - - actor - - targets - - context - AuditLogEventIngestionDto: + - object + - data + UserlandUserOrganizationMembershipBaseList: type: object properties: - organization_id: + object: type: string - description: The unique ID of the Organization. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - event: - description: The audit log event to create. - $ref: '#/components/schemas/AuditLogEventDto' + description: Indicates this is a list response. + const: list + data: + type: array + items: + type: object + properties: + object: + type: string + description: Distinguishes the organization membership object. + const: organization_membership + id: + type: string + description: The unique ID of the organization membership. + example: om_01HXYZ123456789ABCDEFGHIJ + user_id: + type: string + description: The ID of the user. + example: user_01EHQTV6MWP9P1F4ZXGXMC8ABB + organization_id: + type: string + description: The ID of the organization which the user belongs to. + example: org_01EHZNVPK3SFK441A1RGBFSHRT + status: + type: string + enum: + - active + - inactive + - pending + description: >- + The status of the organization membership. One of `active`, + `inactive`, or `pending`. + example: active + directory_managed: + type: boolean + description: >- + Whether this organization membership is managed by a directory + sync connection. + example: false + organization_name: + type: string + description: The name of the organization which the user belongs to. + example: Acme Corp + custom_attributes: + type: object + additionalProperties: {} + description: >- + An object containing IdP-sourced attributes from the linked + [Directory User](/reference/directory-sync/directory-user) or + [SSO Profile](/reference/sso/profile). Directory User + attributes take precedence when both are linked. + example: + department: Engineering + title: Developer Experience Engineer + location: Brooklyn + 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 + - user_id + - organization_id + - status + - directory_managed + - created_at + - updated_at + 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: om_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: om_01HXYZ987654321KJIHGFEDCBA + required: + - before + - after + description: Pagination cursors for navigating between pages of results. required: - - organization_id - - event - AuditLogExportCreationDto: + - object + - data + - list_metadata + Connection: type: object properties: + object: + type: string + description: Distinguishes the Connection object. + const: connection + id: + type: string + description: Unique identifier for the Connection. + example: conn_01E4ZCR3C56J083X43JQXF3JK5 organization_id: type: string - description: The unique ID of the Organization. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - range_start: + description: >- + Unique identifier for the Organization in which the Connection + resides. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + connection_type: type: string - description: ISO-8601 value for start of the export range. - example: '2022-07-02T18:09:06.996Z' - range_end: + enum: + - Pending + - ADFSSAML + - AdpOidc + - AppleOAuth + - Auth0Migration + - Auth0SAML + - AzureSAML + - BitbucketOAuth + - CasSAML + - ClassLinkSAML + - CleverOIDC + - CloudflareSAML + - CyberArkSAML + - DiscordOAuth + - DuoSAML + - EntraIdOIDC + - GenericOIDC + - GenericSAML + - GitHubOAuth + - GitLabOAuth + - GoogleOAuth + - GoogleOIDC + - GoogleSAML + - IntuitOAuth + - JumpCloudSAML + - KeycloakSAML + - LastPassSAML + - LinkedInOAuth + - LoginGovOidc + - MagicLink + - MicrosoftOAuth + - MiniOrangeSAML + - NetIqSAML + - OktaOIDC + - OktaSAML + - OneLoginSAML + - OracleSAML + - PingFederateSAML + - PingOneSAML + - RipplingSAML + - SalesforceSAML + - ShibbolethGenericSAML + - ShibbolethSAML + - SimpleSamlPhpSAML + - SalesforceOAuth + - SlackOAuth + - TestIdp + - VercelMarketplaceOAuth + - VercelOAuth + - VMwareSAML + - XeroOAuth + description: >- + The type of the SSO Connection used to authenticate the user. The + Connection type may be used to dynamically generate authorization + URLs. + example: OktaSAML + name: type: string - description: ISO-8601 value for end of the export range. - example: '2022-09-02T18:09:06.996Z' - actions: - description: List of actions to filter against. - example: - - user.signed_in - type: array - items: - type: string - actors: - description: Deprecated. Use `actor_names` instead. + description: >- + A human-readable name for the Connection. This will most commonly be + the organization's name. + example: Foo Corp + state: + type: string + enum: + - requires_type + - draft + - active + - validating + - inactive + - deleting + description: Indicates whether a Connection is able to authenticate users. + example: active + status: + type: string + enum: + - linked + - unlinked + description: Deprecated. Use `state` instead. deprecated: true - example: - - Jon Smith - type: array - items: - type: string - actor_names: - description: List of actor names to filter against. - example: - - Jon Smith - type: array - items: - type: string - actor_ids: - description: List of actor IDs to filter against. - example: - - user_01GBZK5MP7TD1YCFQHFR22180V - type: array - items: - type: string - targets: - description: List of target types to filter against. - example: - - team + example: linked + domains: type: array items: - type: string + type: object + properties: + id: + type: string + description: Unique identifier for the Connection Domain. + example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A + object: + type: string + description: Distinguishes the Connection Domain object. + const: connection_domain + domain: + type: string + description: The domain value. + example: foo-corp.com + required: + - id + - object + - domain + description: List of Organization Domains. + options: + type: object + properties: + signing_cert: + type: + - string + - 'null' + description: The signing certificate of the SAML connection. + example: null + required: + - signing_cert + description: >- + Configuration options for SAML connections. Only present for SAML + connection types. + 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: - - organization_id - - range_start - - range_end - UpdateAuditLogsRetentionDto: + - object + - id + - connection_type + - name + - state + - status + - domains + - created_at + - updated_at + ConnectionList: type: object properties: - retention_period_in_days: - type: number - description: >- - The number of days Audit Log events will be retained. Valid values - are `30` and `365`. - example: 30 - required: - - retention_period_in_days - AuditLogSchemaActorDto: + object: + type: string + description: Indicates this is a list response. + const: list + data: + type: array + items: + $ref: '#/components/schemas/Connection' + 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: conn_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: conn_01HXYZ987654321KJIHGFEDCBA + required: + - before + - after + description: Pagination cursors for navigating between pages of results. + required: + - object + - data + - list_metadata + - list_metadata + CorsOriginResponse: type: object properties: - metadata: - type: object - description: JSON schema for actor metadata. - example: - type: object - properties: - role: - type: string + object: + type: string + description: Distinguishes the CORS origin object. + const: cors_origin + id: + type: string + description: Unique identifier of the CORS origin. + example: cors_origin_01HXYZ123456789ABCDEFGHIJ + origin: + type: string + description: The origin URL. + example: https://example.com + created_at: + type: string + format: date-time + description: Timestamp when the CORS origin was created. + example: '2026-01-15T12:00:00.000Z' + updated_at: + type: string + format: date-time + description: Timestamp when the CORS origin was last updated. + example: '2026-01-15T12:00:00.000Z' required: - - metadata - AuditLogSchemaTargetDto: + - object + - id + - origin + - created_at + - updated_at + Directory: type: object properties: + object: + type: string + description: Distinguishes the Directory object. + const: directory + id: + type: string + description: Unique identifier for the Directory. + example: directory_01ECAZ4NV9QMV47GW873HDCX74 + organization_id: + type: string + description: >- + The unique identifier for the Organization in which the directory + resides. + example: org_01EHZNVPK3SFK441A1RGBFSHRT + external_key: + type: string + description: External Key for the Directory. + example: sPa12dwRQ type: type: string - description: The type of the target resource. - example: invoice + enum: + - pending + - azure scim v2.0 + - bamboohr + - breathe hr + - cezanne hr + - cyberark scim v2.0 + - fourth hr + - generic scim v2.0 + - gsuite directory + - hibob + - sailpoint scim v2.0 + - jump cloud scim v2.0 + - okta scim v2.0 + - onelogin scim v2.0 + - people hr + - personio + - pingfederate scim v2.0 + - rippling scim v2.0 + - s3 + - sftp + - sftp workday + - workday + - gusto + - rippling + description: The type of external Directory Provider integrated with. + example: gsuite directory + state: + type: string + enum: + - requires_type + - linked + - validating + - invalid_credentials + - unlinked + - deleting + description: >- + Describes whether the Directory has been successfully connected to + an external provider. + example: unlinked + name: + type: string + description: The name of the directory. + example: Foo Corp + domain: + type: string + description: The URL associated with an Enterprise Client. + example: foo-corp.com metadata: type: object - description: Optional JSON schema for target metadata. - example: - type: object - properties: - cost: - type: number + properties: + users: + type: object + properties: + active: + type: number + description: Count of active directory users. + example: 42 + inactive: + type: number + description: Count of inactive directory users. + example: 3 + required: + - active + - inactive + description: Counts of active and inactive directory users. + groups: + type: number + description: Count of directory groups. + example: 5 + required: + - users + - groups + description: >- + Aggregate counts of directory users and groups synced from the + provider. + 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 + - organization_id + - external_key - type - AuditLogSchemaDto: + - state + - name + - created_at + - updated_at + DirectoryList: type: object properties: - actor: - description: The metadata schema for the actor. - $ref: '#/components/schemas/AuditLogSchemaActorDto' - targets: - description: The list of targets for the schema. + object: + type: string + description: Indicates this is a list response. + const: list + data: type: array items: - $ref: '#/components/schemas/AuditLogSchemaTargetDto' - metadata: + $ref: '#/components/schemas/Directory' + description: The list of records for the current page. + list_metadata: type: object - description: Optional JSON schema for event metadata. - example: - type: object - properties: - extra: - type: string + 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: directory_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: directory_01HXYZ987654321KJIHGFEDCBA + required: + - before + - after + description: Pagination cursors for navigating between pages of results. required: - - targets - ChallengeAuthenticationFactorDto: + - object + - data + - list_metadata + - list_metadata + DirectoryGroup: type: object properties: - sms_template: + object: + type: string + description: Distinguishes the Directory Group object. + const: directory_group + id: + type: string + description: Unique identifier for the Directory Group. + example: directory_group_01E1JJS84MFPPQ3G655FHTKX6Z + idp_id: type: string description: >- - A custom template for the SMS message. Use the {{code}} placeholder - to include the verification code. - example: Your verification code is {{code}}. - CheckAuthorizationDto: - type: object - properties: - permission_slug: + Unique identifier for the group, assigned by the Directory Provider. + Different Directory Providers use different ID formats. + example: 02grqrue4294w24 + directory_id: type: string - description: The slug of the permission to check. - example: posts:create - resource_id: + description: The identifier of the Directory the Directory Group belongs to. + example: directory_01ECAZ4NV9QMV47GW873HDCX74 + organization_id: type: string - description: The ID of the resource. - example: resource_01HXYZ123456789ABCDEFGHIJ - resource_external_id: + description: The identifier for the Organization in which the Directory resides. + example: org_01EZTR6WYX1A0DSE2CYMGXQ24Y + name: type: string - description: The external ID of the resource. - example: my-custom-id - resource_type_slug: + description: The name of the Directory Group. + example: Developers + raw_attributes: + type: object + additionalProperties: {} + description: The raw attributes received from the directory provider. + created_at: + format: date-time type: string - description: The slug of the resource type. - example: document + 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: - - permission_slug - AssignRoleDto: + - object + - id + - idp_id + - directory_id + - organization_id + - name + - created_at + - updated_at + DirectoryGroupList: type: object properties: - role_slug: - type: string - description: The slug of the role to assign. - example: editor - resource_id: - type: string - description: >- - The ID of the resource. Use either this or `resource_external_id` - and `resource_type_slug`. - example: authz_resource_01HXYZ123456789ABCDEFGH - resource_external_id: - type: string - description: The external ID of the resource. Requires `resource_type_slug`. - example: external_01HXYZ123456789ABCDEFGH - resource_type_slug: + object: type: string - description: The resource type slug. Required with `resource_external_id`. - example: project + description: Indicates this is a list response. + const: list + data: + type: array + items: + $ref: '#/components/schemas/DirectoryGroup' + 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: directory_group_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: directory_group_01HXYZ987654321KJIHGFEDCBA + required: + - before + - after + description: Pagination cursors for navigating between pages of results. required: - - role_slug - RemoveRoleDto: + - object + - data + - list_metadata + - list_metadata + DirectoryUserWithGroups: type: object properties: - role_slug: + object: type: string - description: The slug of the role to remove. - example: editor - resource_id: + description: Distinguishes the Directory User object. + const: directory_user + id: type: string - description: >- - The ID of the resource. Use either this or `resource_external_id` - and `resource_type_slug`. - example: authz_resource_01HXYZ123456789ABCDEFGH - resource_external_id: + description: Unique identifier for the Directory User. + example: directory_user_01E1JG7J09H96KYP8HM9B0G5SJ + directory_id: type: string - description: The external ID of the resource. Requires `resource_type_slug`. - example: external_01HXYZ123456789ABCDEFGH - resource_type_slug: + description: The identifier of the Directory the Directory User belongs to. + example: directory_01ECAZ4NV9QMV47GW873HDCX74 + organization_id: type: string - description: The resource type slug. Required with `resource_external_id`. - example: project - required: - - role_slug - SetRolePermissionsDto: - type: object - properties: - permissions: - description: The permission slugs to assign to the role. + description: The identifier for the Organization in which the Directory resides. + example: org_01EZTR6WYX1A0DSE2CYMGXQ24Y + idp_id: + type: string + description: >- + Unique identifier for the user, assigned by the Directory Provider. + Different Directory Providers use different ID formats. + example: '2836' + email: + type: + - string + - 'null' + description: The email address of the user. + example: marcelina.davis@example.com + first_name: + type: + - string + - 'null' + description: The first name of the user. + example: Marcelina + last_name: + type: + - string + - 'null' + description: The last name of the user. + example: Davis + emails: + type: array + items: + type: object + properties: + primary: + type: boolean + description: Whether this is the primary email address. + example: true + type: + type: string + description: The type of email address. + example: work + value: + type: + - string + - 'null' + description: The email address value. + example: marcelina.davis@example.com + description: A list of email addresses for the user. + job_title: + type: + - string + - 'null' + description: The job title of the user. + example: Software Engineer + username: + type: + - string + - 'null' + description: The username of the user. + example: mdavis + state: + type: string + enum: + - active + - suspended + - inactive + description: The state of the user. + example: active + raw_attributes: + type: object + additionalProperties: {} + description: The raw attributes received from the directory provider. + custom_attributes: + type: object + additionalProperties: {} + description: >- + An object containing the custom attribute mapping for the Directory + Provider. example: - - billing:read - - billing:write - - invoices:manage - - reports:view + department: Engineering + job_title: Software Engineer + role: + $ref: '#/components/schemas/SlimRole' + description: The primary role assigned to the user. + roles: + type: array + items: + $ref: '#/components/schemas/SlimRole' + description: All roles assigned to the user. + 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' + groups: type: array items: - type: string + $ref: '#/components/schemas/DirectoryGroup' + description: The directory groups the user belongs to. required: - - permissions - AddRolePermissionDto: + - object + - id + - directory_id + - organization_id + - idp_id + - email + - state + - raw_attributes + - custom_attributes + - created_at + - updated_at + - groups + DirectoryUserList: type: object properties: - slug: + object: type: string - description: The slug of the permission to add to the role. - example: reports:export + description: Indicates this is a list response. + const: list + data: + type: array + items: + $ref: '#/components/schemas/DirectoryUserWithGroups' + 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: directory_user_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: directory_user_01HXYZ987654321KJIHGFEDCBA + required: + - before + - after + description: Pagination cursors for navigating between pages of results. required: - - slug - CreateOrganizationRoleDto: + - object + - data + - list_metadata + - list_metadata + Event: type: object properties: - slug: + object: type: string - maxLength: 48 - description: >- - A unique identifier for the role within the organization. Must begin - with 'org-' and contain only lowercase letters, numbers, hyphens, - and underscores. - example: org-billing-admin - name: + description: Distinguishes the Event object. + const: event + id: type: string - maxLength: 48 - description: A descriptive name for the role. - example: Billing Administrator - description: - type: - - string - - 'null' - maxLength: 150 - description: An optional description of the role's purpose. - example: Can manage billing and invoices + description: Unique identifier for the Event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + description: The type of event that occurred. + example: dsync.user.created + data: + type: object + additionalProperties: {} + description: The event payload. + example: + id: directory_user_01E1JG7J09H96KYP8HM9B0G5SJ + state: active + emails: + - primary: true + value: veda@foo-corp.com + idp_id: '2836' + object: directory_user + username: veda@foo-corp.com + last_name: Torp + first_name: Veda + directory_id: directory_01ECAZ4NV9QMV47GW873HDCX74 + raw_attributes: {} + custom_attributes: {} + created_at: '2021-06-25T19:07:33.155Z' + updated_at: '2021-06-25T19:07:33.155Z' + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + type: object + additionalProperties: {} + description: Additional context about the event. required: - - slug - - name - UpdateOrganizationRolePriorityOrderDto: + - object + - id + - event + - data + - created_at + EventList: type: object properties: - role_priority_order: - description: An ordered list of role IDs defining the priority order. - example: - - role_01EHQMYV6MBK39QC5PZXHY59C3 + object: + type: string + description: Indicates this is a list response. + const: list + data: type: array items: - type: string + $ref: '#/components/schemas/Event' + description: The list of records for the current page. + list_metadata: + type: object + properties: + 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: event_01EHZNVPK3SFK441A1RGBFSHRT + required: + - after + description: Pagination cursor for navigating to the next page of results. required: - - role_priority_order - UpdateOrganizationRoleDto: + - object + - data + - list_metadata + JwtTemplateResponse: type: object properties: - name: + object: type: string - maxLength: 48 - description: A descriptive name for the role. - example: Billing Administrator - description: - type: - - string - - 'null' - maxLength: 150 - description: An optional description of the role's purpose. - example: Can manage billing and invoices - CreateAuthorizationPermissionDto: - type: object - properties: - slug: + description: The object type. + const: jwt_template + content: 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: + description: The JWT template content as a Liquid template string. + example: '{"iss": "{{environment.id}}", "sub": "{{user.id}}"}' + created_at: 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: + description: The timestamp when the JWT template was created. + example: '2026-01-15T12:00:00.000Z' + updated_at: type: string - maxLength: 48 - description: The slug of the resource type this permission is scoped to. - example: document + description: The timestamp when the JWT template was last updated. + example: '2026-01-15T12:00:00.000Z' required: - - slug - - name - UpdateAuthorizationPermissionDto: + - object + - content + - created_at + - updated_at + OrganizationDomainStandAlone: type: object properties: - name: + object: 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 - CreateRoleDto: - type: object - properties: - slug: + description: Distinguishes the organization domain object. + const: organization_domain + id: type: string - maxLength: 48 - description: A unique slug for the role. - example: editor - name: + description: Unique identifier of the organization domain. + example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A + organization_id: type: string - maxLength: 48 - description: A descriptive name for the role. - example: Editor - description: - type: - - string - - 'null' - maxLength: 150 - description: An optional description of the role. - example: Can edit resources - resource_type_slug: + description: ID of the parent Organization. + example: org_01HE8GSH8FQPASKSY27THRKRBP + domain: type: string - maxLength: 48 - description: The slug of the resource type the role is scoped to. - example: default - required: - - slug - - name - UpdateRoleDto: - type: object - properties: - name: + description: Domain for the organization domain. + example: foo-corp.com + state: type: string - maxLength: 48 - description: A descriptive name for the role. - example: Editor - description: - type: - - string - - 'null' - maxLength: 150 - description: An optional description of the role. - example: Can edit resources - UpdateAuthorizationResourceDto: - type: object - properties: - name: + enum: + - failed + - legacy_verified + - pending + - unverified + - verified + description: Verification state of the domain. + example: pending + verification_prefix: type: string - maxLength: 48 - description: A display name for the resource. - example: Updated Name - description: - type: - - string - - 'null' - maxLength: 150 - description: An optional description of the resource. - example: Updated description - CreateAuthorizationResourceDto: + description: The prefix used in DNS verification. + example: superapp-domain-verification-z3kjny + verification_token: + type: string + description: Validation token to be used in DNS TXT record. + example: m5Oztg3jdK4NJLgs8uIlIprMw + verification_strategy: + type: string + enum: + - dns + - manual + description: Strategy used to verify the domain. + example: dns + 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 + - organization_id + - domain + - created_at + - updated_at + Flag: type: object properties: - external_id: - type: string - maxLength: 128 - description: An external identifier for the resource. - example: my-workspace-01 - name: + object: type: string - maxLength: 48 - description: A display name for the resource. - example: Acme Workspace - description: - type: - - string - - 'null' - maxLength: 150 - description: An optional description of the resource. - example: Primary workspace for the Acme team - resource_type_slug: + description: Distinguishes the Feature Flag object. + const: feature_flag + id: type: string - description: The slug of the resource type. - example: workspace - organization_id: + description: Unique identifier of the Feature Flag. + example: flag_01EHZNVPK3SFK441A1RGBFSHRT + slug: type: string - description: The ID of the organization this resource belongs to. - example: org_01EHQMYV6MBK39QC5PZXHY59C3 - parent_resource_id: + description: A unique key to reference the Feature Flag. + example: advanced-analytics + name: + type: string + description: >- + A descriptive name for the Feature Flag. This field does not need to + be unique. + example: Advanced Analytics + description: type: - string - 'null' - description: The ID of the parent resource. - example: resource_01HXYZ123456789ABCDEFGHIJ - parent_resource_external_id: + description: A description for the Feature Flag. + example: Enable advanced analytics dashboard feature + owner: + description: The owner of the Feature Flag. + oneOf: + - type: object + properties: + email: + type: string + description: The email address of the flag owner. + example: jane@example.com + first_name: + type: + - string + - 'null' + description: The first name of the flag owner. + example: Jane + last_name: + type: + - string + - 'null' + description: The last name of the flag owner. + example: Doe + required: + - email + - first_name + - last_name + - type: 'null' + tags: + type: array + items: + type: string + description: Labels assigned to the Feature Flag for categorizing and filtering. + example: + - reports + enabled: + type: boolean + description: >- + Specifies whether the Feature Flag is active for the current + environment. + example: true + default_value: + type: boolean + description: >- + The value returned for users and organizations who don't match any + configured targeting rules. + example: false + created_at: + format: date-time type: string - description: The external ID of the parent resource. - example: parent-workspace-01 - parent_resource_type_slug: + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + updated_at: + format: date-time type: string - description: The resource type slug of the parent resource. - example: workspace + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' required: - - external_id + - object + - id + - slug - name - - resource_type_slug - - organization_id - CreateCorsOriginDto: + - description + - owner + - tags + - enabled + - default_value + - created_at + - updated_at + FlagList: type: object properties: - origin: + object: type: string - description: The origin URL to allow for CORS requests. - example: https://example.com + description: Indicates this is a list response. + const: list + data: + type: array + items: + $ref: '#/components/schemas/Flag' + 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: flag_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: flag_01HXYZ987654321KJIHGFEDCBA + required: + - before + - after + description: Pagination cursors for navigating between pages of results. required: - - origin - UpdateJwtTemplateDto: + - object + - data + - list_metadata + ApiKeyList: type: object properties: - content: + object: type: string - description: The JWT template content as a Liquid template string. - example: '{"iss": "{{environment.id}}", "sub": "{{user.id}}"}' + description: Indicates this is a list response. + const: list + data: + type: array + items: + $ref: '#/components/schemas/ApiKey' + 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: api_key_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: api_key_01HXYZ987654321KJIHGFEDCBA + required: + - before + - after + description: Pagination cursors for navigating between pages of results. required: - - content - CreateOrganizationDomainDto: + - object + - data + - list_metadata + ApiKeyWithValue: type: object properties: - domain: + object: type: string - description: The domain to add to the organization. - example: foo-corp.com - organization_id: + description: Distinguishes the API Key object. + const: api_key + id: type: string - description: The ID of the organization to add the domain to. - example: org_01EHQMYV6MBK39QC5PZXHY59C3 - required: - - domain - - organization_id - CreateOrganizationApiKeyDto: - type: object - properties: + description: Unique identifier of the API Key. + example: api_key_01EHZNVPK3SFK441A1RGBFSHRT + owner: + type: object + properties: + type: + type: string + description: The type of the API Key owner. + example: organization + const: organization + id: + type: string + description: Unique identifier of the API Key owner. + example: org_01EHZNVPK3SFK441A1RGBFSHRT + required: + - type + - id + description: The entity that owns the API Key. name: type: string - description: The name for the API key. + description: A descriptive name for the API Key. example: Production API Key + obfuscated_value: + type: string + description: An obfuscated representation of the API Key value. + example: sk_...3456 + last_used_at: + type: + - string + - 'null' + description: Timestamp of when the API Key was last used. + example: null permissions: - description: The permission slugs to assign to the API key. - example: - - posts:read - - posts:write type: array items: type: string + description: The permission slugs assigned to the API Key. + 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' + value: + type: string + description: The full API Key value. Only returned once at creation time. + example: sk_abcdefghijklmnop123456 required: + - object + - id + - owner - name - OrganizationDomainDataDto: + - obfuscated_value + - last_used_at + - permissions + - created_at + - updated_at + - value + Organization: type: object properties: - domain: + object: type: string - description: The domain value. - example: foo-corp.com - state: + description: Distinguishes the Organization object. + const: organization + id: type: string - enum: - - pending - - verified - description: The verification state of the domain. - example: verified - required: - - domain - - state - OrganizationDto: - type: object - properties: + description: Unique identifier of the Organization. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY name: type: string - description: The name of the organization. - example: Foo Corp - allow_profiles_outside_organization: - type: boolean description: >- - Whether the organization allows profiles from outside the - organization to sign in. - example: false + A descriptive name for the Organization. This field does not need to + be unique. + example: Acme Inc. domains: - description: >- - The domains associated with the organization. Deprecated in favor of - `domain_data`. - example: - - example.com type: array items: - type: string - domain_data: - description: >- - The domains associated with the organization, including verification - state. - type: array - items: - $ref: '#/components/schemas/OrganizationDomainDataDto' + type: object + properties: + object: + type: string + description: Distinguishes the organization domain object. + const: organization_domain + id: + type: string + description: Unique identifier of the organization domain. + example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A + organization_id: + type: string + description: ID of the parent Organization. + example: org_01HE8GSH8FQPASKSY27THRKRBP + domain: + type: string + description: Domain for the organization domain. + example: foo-corp.com + state: + type: string + enum: + - failed + - legacy_verified + - pending + - unverified + - verified + description: Verification state of the domain. + example: pending + verification_prefix: + type: string + description: The prefix used in DNS verification. + example: superapp-domain-verification-z3kjny + verification_token: + type: string + description: Validation token to be used in DNS TXT record. + example: m5Oztg3jdK4NJLgs8uIlIprMw + verification_strategy: + type: string + enum: + - dns + - manual + description: Strategy used to verify the domain. + example: dns + 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 + - organization_id + - domain + - created_at + - updated_at + description: List of Organization Domains. metadata: - type: - - object - - 'null' - additionalProperties: &ref_2 + type: object + additionalProperties: type: string maxLength: 600 - maxProperties: 50 - example: &ref_3 - tier: diamond description: >- Object containing [metadata](/authkit/metadata) key/value pairs associated with the Organization. - propertyNames: - maxLength: 40 - external_id: - type: - - string - - 'null' - maxLength: 128 - example: ext_12345 - description: An external identifier for the Organization. - required: - - name - UpdateOrganizationDto: - type: object - properties: - name: - type: string - description: The name of the organization. - example: Foo Corp - allow_profiles_outside_organization: - type: boolean - description: >- - Whether the organization allows profiles from outside the - organization to sign in. - example: false - domains: - description: >- - The domains associated with the organization. Deprecated in favor of - `domain_data`. example: - - foo-corp.com - deprecated: true - type: array - items: - type: string - domain_data: - description: >- - The domains associated with the organization, including verification - state. - type: array - items: - $ref: '#/components/schemas/OrganizationDomainDataDto' - stripe_customer_id: - type: string - description: The Stripe customer ID associated with the organization. - example: cus_R9qWAGMQ6nGE7V - metadata: - type: - - object - - 'null' - additionalProperties: *ref_2 - maxProperties: 50 - example: *ref_3 - description: >- - Object containing [metadata](/authkit/metadata) key/value pairs - associated with the Organization. + tier: diamond propertyNames: maxLength: 40 + maxProperties: 50 external_id: type: - - string - - 'null' - maxLength: 128 - example: 2fe01467-f7ea-4dd2-8b79-c2b4f56d0191 - description: An external identifier for the Organization. - SsoIntentOptions: - type: object - properties: - bookmark_slug: + - string + - 'null' + description: The external ID of the Organization. + example: 2fe01467-f7ea-4dd2-8b79-c2b4f56d0191 + stripe_customer_id: type: string - description: The bookmark slug to use for SSO. - example: chatgpt - provider_type: + description: The Stripe customer ID of the Organization. + example: cus_R9qWAGMQ6nGE7V + created_at: + format: date-time type: string - description: The SSO provider type to configure. - example: GoogleSAML - const: GoogleSAML - IntentOptions: + 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' + allow_profiles_outside_organization: + type: boolean + description: >- + Whether the Organization allows profiles outside of its managed + domains. + example: false + required: + - object + - id + - name + - domains + - metadata + - external_id + - created_at + - updated_at + - allow_profiles_outside_organization + OrganizationList: type: object properties: - sso: - description: SSO-specific options for the Admin Portal. - $ref: '#/components/schemas/SsoIntentOptions' + object: + type: string + description: Indicates this is a list response. + const: list + data: + type: array + items: + $ref: '#/components/schemas/Organization' + 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: org_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: org_01HXYZ987654321KJIHGFEDCBA + required: + - before + - after + description: Pagination cursors for navigating between pages of results. required: - - sso - GenerateLinkDto: + - object + - data + - list_metadata + - list_metadata + AuditLogConfiguration: type: object properties: - return_url: - type: string - description: >- - The URL to go to when an admin clicks on your logo in the Admin - Portal. If not specified, the return URL configured on the - [Redirects](https://dashboard.workos.com/redirects) page will be - used. - example: https://example.com/admin-portal/return - success_url: - type: string - description: >- - The URL to redirect the admin to when they finish setup. If not - specified, the success URL configured on the - [Redirects](https://dashboard.workos.com/redirects) page will be - used. - example: https://example.com/admin-portal/success - organization: + organization_id: type: string - description: An [Organization](/reference/organization) identifier. + description: Unique identifier of the Organization. example: org_01EHZNVPK3SFK441A1RGBFSHRT - intent: + retention_period_in_days: + type: number + description: >- + The number of days Audit Log events will be retained before being + permanently deleted. + example: 30 + state: type: string - description: |2- - - The intent of the Admin Portal. - - `sso` - Launch Admin Portal for creating SSO connections - - `dsync` - Launch Admin Portal for creating Directory Sync connections - - `audit_logs` - Launch Admin Portal for viewing Audit Logs - - `log_streams` - Launch Admin Portal for creating Log Streams - - `domain_verification` - Launch Admin Portal for Domain Verification - - `certificate_renewal` - Launch Admin Portal for renewing SAML Certificates - - `bring_your_own_key` - Launch Admin Portal for configuring Bring Your Own Key - example: sso enum: - - sso - - dsync - - audit_logs - - log_streams - - domain_verification - - certificate_renewal - - bring_your_own_key - intent_options: - description: Options to configure the Admin Portal based on the intent. - $ref: '#/components/schemas/IntentOptions' + - active + - inactive + - disabled + description: >- + The current state of the audit log configuration for the + organization. + example: active + log_stream: + type: object + properties: + id: + type: string + description: Unique identifier of the Audit Log Stream. + example: als_01EHZNVPK3SFK441A1RGBFSHRT + type: + type: string + enum: + - AzureSentinel + - Datadog + - GenericHttps + - GoogleCloudStorage + - S3 + - Splunk + description: The type of the Audit Log Stream destination. + example: Datadog + state: + type: string + enum: + - active + - inactive + - error + - invalid + description: The current state of the Audit Log Stream. + example: active + last_synced_at: + type: + - string + - 'null' + description: >- + ISO-8601 timestamp of when the last event was successfully + synced, or null if no events have been synced. + example: '2026-01-15T12:00:00.000Z' + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + required: + - id + - type + - state + - last_synced_at + - created_at + description: >- + The Audit Log Stream currently configured for the organization, if + any. required: - - organization - CreateRedirectUriDto: + - organization_id + - retention_period_in_days + - state + DataIntegrationAuthorizeUrlResponse: type: object properties: - uri: + url: type: string - description: The redirect URI to create. - example: https://example.com/callback + description: The OAuth authorization URL to redirect the user to. + example: >- + https://api.workos.com/data-integrations/q2czJKmVAraSBg8xFpT7M9uR/authorize-redirect required: - - uri - EnrollUserlandUserAuthenticationFactorDto: + - url + DataIntegrationAccessTokenResponse: + oneOf: + - type: object + properties: + active: + type: boolean + description: >- + Indicates whether the access token is valid and ready for use, + or if reauthorization is required. + const: true + access_token: + type: object + properties: + object: + type: string + description: Distinguishes the access token object. + const: access_token + access_token: + type: string + description: The OAuth access token for the connected integration. + example: gho_16C7e42F292c6912E7710c838347Ae178B4a + expires_at: + type: + - string + - 'null' + description: >- + The ISO-8601 formatted timestamp indicating when the access + token expires. + example: '2025-12-31T23:59:59.000Z' + scopes: + type: array + items: + type: string + description: The scopes granted to the access token. + example: + - repo + - user:email + missing_scopes: + type: array + items: + type: string + description: >- + If the integration has requested scopes that aren't present + on the access token, they're listed here. + example: [] + required: + - object + - access_token + - expires_at + - scopes + - missing_scopes + description: >- + The [access token](/reference/pipes/access-token) object, + present when `active` is `true`. + required: + - active + - access_token + - type: object + properties: + active: + type: boolean + description: >- + Indicates whether the access token is valid and ready for use, + or if reauthorization is required. + const: false + error: + type: string + enum: + - needs_reauthorization + - not_installed + description: >- + - `"not_installed"`: The user does not have the integration + installed. + + - `"needs_reauthorization"`: The user needs to reauthorize the + integration. + example: not_installed + required: + - active + - error + ConnectedAccount: type: object properties: - type: + object: type: string - description: The type of the factor to enroll. - example: totp - const: totp - totp_issuer: + description: Distinguishes the connected account object. + const: connected_account + id: type: string + description: The unique identifier of the connected account. + example: data_installation_01EHZNVPK3SFK441A1RGBFSHRT + user_id: + type: + - string + - 'null' description: >- - Your application or company name displayed in the user's - authenticator app. - example: WorkOS - totp_user: + The [User](/reference/authkit/user) identifier associated with this + connection. + example: user_01EHZNVPK3SFK441A1RGBFSHRT + organization_id: + type: + - string + - 'null' + description: >- + The [Organization](/reference/organization) identifier associated + with this connection, or `null` if not scoped to an organization. + example: null + scopes: + type: array + items: + type: string + description: The OAuth scopes granted for this connection. + example: + - repo + - user:email + state: type: string - description: The user's account name displayed in their authenticator app. - example: user@example.com - totp_secret: + enum: + - connected + - needs_reauthorization + - disconnected + description: >- + The state of the connected account: + + - `connected`: The connection is active and tokens are valid. + + - `needs_reauthorization`: The user needs to reauthorize the + connection, typically because required scopes have changed. + + - `disconnected`: The connection has been disconnected. + example: connected + created_at: + type: string + description: The timestamp when the connection was created. + example: '2024-01-16T14:20:00.000Z' + updated_at: + type: string + description: The timestamp when the connection was last updated. + example: '2024-01-16T14:20:00.000Z' + required: + - object + - id + - user_id + - organization_id + - scopes + - state + - created_at + - updated_at + DataIntegrationsListResponse: + type: object + properties: + object: type: string + description: Indicates this is a list response. + const: list + data: + type: array + items: + type: object + properties: + object: + type: string + description: Distinguishes the data provider object. + const: data_provider + id: + type: string + description: The unique identifier of the provider. + example: data_integration_01EHZNVPK3SFK441A1RGBFSHRT + name: + type: string + description: The display name of the provider (e.g., "GitHub", "Slack"). + example: GitHub + description: + type: + - string + - 'null' + description: >- + A description of the provider explaining how it will be used, + if configured. + example: Connect your GitHub account to access repositories. + slug: + type: string + description: >- + The slug identifier used in API calls (e.g., `github`, + `slack`, `notion`). + example: github + integration_type: + type: string + description: The type of integration (e.g., `github`, `slack`). + example: github + credentials_type: + type: string + description: The type of credentials used by the provider (e.g., `oauth2`). + example: oauth2 + scopes: + description: >- + The OAuth scopes configured for this provider, or `null` if + none are configured. + example: + - repo + - user:email + oneOf: + - type: array + items: + type: string + - type: 'null' + ownership: + type: string + enum: + - userland_user + - organization + description: Whether the provider is owned by a user or organization. + created_at: + type: string + description: The timestamp when the provider was created. + example: '2024-01-15T10:30:00.000Z' + updated_at: + type: string + description: The timestamp when the provider was last updated. + example: '2024-01-15T10:30:00.000Z' + integrationType: + type: string + deprecated: true + description: Use integration_type instead. + credentialsType: + type: string + deprecated: true + description: Use credentials_type instead. + createdAt: + type: string + deprecated: true + description: Use created_at instead. + updatedAt: + type: string + deprecated: true + description: Use updated_at instead. + connected_account: + description: >- + The user's [connected + account](/reference/pipes/connected-account) for this + provider, or `null` if the user has not connected. + oneOf: + - type: object + properties: + object: + type: string + description: Distinguishes the connected account object. + const: connected_account + id: + type: string + description: The unique identifier of the connected account. + example: data_installation_01EHZNVPK3SFK441A1RGBFSHRT + user_id: + type: + - string + - 'null' + description: >- + The [User](/reference/authkit/user) identifier + associated with this connection. + example: user_01EHZNVPK3SFK441A1RGBFSHRT + organization_id: + type: + - string + - 'null' + description: >- + The [Organization](/reference/organization) identifier + associated with this connection, or `null` if not + scoped to an organization. + example: null + scopes: + type: array + items: + type: string + description: The OAuth scopes granted for this connection. + example: + - repo + - user:email + state: + type: string + enum: + - connected + - needs_reauthorization + - disconnected + description: >- + The state of the connected account: + + - `connected`: The connection is active and tokens are + valid. + + - `needs_reauthorization`: The user needs to + reauthorize the connection, typically because required + scopes have changed. + + - `disconnected`: The connection has been + disconnected. + example: connected + created_at: + type: string + description: The timestamp when the connection was created. + example: '2024-01-16T14:20:00.000Z' + updated_at: + type: string + description: The timestamp when the connection was last updated. + example: '2024-01-16T14:20:00.000Z' + userlandUserId: + type: + - string + - 'null' + deprecated: true + description: Use `user_id` instead. + organizationId: + type: + - string + - 'null' + deprecated: true + description: Use `organization_id` instead. + createdAt: + type: string + deprecated: true + description: Use `created_at` instead. + updatedAt: + type: string + deprecated: true + description: Use `updated_at` instead. + required: + - object + - id + - user_id + - organization_id + - scopes + - state + - created_at + - updated_at + - userlandUserId + - organizationId + - createdAt + - updatedAt + - type: 'null' + required: + - object + - id + - name + - description + - slug + - integration_type + - credentials_type + - scopes + - ownership + - created_at + - updated_at + - integrationType + - credentialsType + - createdAt + - updatedAt + - connected_account description: >- - The Base32-encoded shared secret for TOTP factors. This can be - provided when creating the auth factor, otherwise it will be - generated. The algorithm used to derive TOTP codes is SHA-1, the - code length is 6 digits, and the timestep is 30 seconds – the secret - must be compatible with these parameters. - example: JBSWY3DPEHPK3PXP + A list of [providers](/reference/pipes/provider), each including a + [`connected_account`](/reference/pipes/connected-account) field with + the user's connection status. required: - - type - CreateUserlandMagicCodeAndReturnDto: + - object + - data + PortalLinkResponse: type: object properties: - email: - type: string - description: The email address to send the magic code to. - example: marcelina.davis@example.com - invitation_token: + link: type: string - description: The invitation token to associate with this magic code. - example: Z1Y2X3W4V5U6T7S8R9Q0P1O2N3 + description: An ephemeral link to initiate the Admin Portal. + example: >- + https://setup.workos.com?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... required: - - email - CreateUserlandUserInviteOptionsDto: + - link + RadarStandaloneResponse: type: object properties: - email: + verdict: type: string - description: The email address of the recipient. - example: marcelina.davis@example.com - organization_id: + enum: + - allow + - block + - challenge + description: The verdict of the risk assessment. + example: block + reason: type: string - description: >- - The ID of the [organization](/reference/organization) that the - recipient will join. - example: org_01E4ZCR3C56J083X43JQXF3JK5 - role_slug: + description: A human-readable reason for the verdict. + example: Detected enabled Radar control + attempt_id: type: string - description: >- - The [role](/authkit/roles) that the recipient will receive when they - join the organization in the invitation. - example: admin - expires_in_days: - type: number - description: >- - How many days the invitations will be valid for. Must be between 1 - and 30 days. Defaults to 7 days if not specified. - example: 7 - inviter_user_id: + description: Unique identifier of the authentication attempt. + example: radar_att_01HZBC6N1EB1ZY7KG32X + control: type: string + enum: + - bot_detection + - brute_force_attack + - credential_stuffing + - domain_sign_up_rate_limit + - ip_sign_up_rate_limit + - impossible_travel + - repeat_sign_up + - stale_account + - unrecognized_device + - restriction description: >- - The ID of the [user](/reference/authkit/user) who invites the - recipient. The invitation email will mention the name of this user. - example: user_01HYGBX8ZGD19949T3BM4FW1C3 - locale: + The Radar control that triggered the verdict. Only present if the + verdict is `block` or `challenge`. + example: bot_detection + blocklist_type: type: string enum: - - af - - am - - ar - - bg - - bn - - bs - - ca - - cs - - da - - de - - de-DE - - el - - en - - en-AU - - en-CA - - en-GB - - en-US - - es - - es-419 - - es-ES - - es-US - - et - - fa - - fi - - fil - - fr - - fr-BE - - fr-CA - - fr-FR - - fy - - gl - - gu - - ha - - he - - hi - - hr - - hu - - hy - - id - - is - - it - - it-IT - - ja - - jv - - ka - - kk - - km - - kn - - ko - - lt - - lv - - mk - - ml - - mn - - mr - - ms - - my - - nb - - ne - - nl - - nl-BE - - nl-NL - - nn - - 'no' - - pa - - pl - - pt - - pt-BR - - pt-PT - - ro - - ru - - sk - - sl - - sq - - sr - - sv - - sw - - ta - - te - - th - - tr - - uk - - ur - - uz - - vi - - zh - - zh-CN - - zh-HK - - zh-TW - - zu + - ip_address + - domain + - email + - device + - user_agent + - device_fingerprint + - country description: >- - The locale to use when rendering the invitation email. See - [supported locales](/authkit/hosted-ui/localization). - example: en + The type of blocklist entry that triggered the verdict. Only present + if the control is `restriction`. + example: ip_address required: - - email - ResendUserlandUserInviteOptionsDto: + - verdict + - reason + - attempt_id + RadarListEntryAlreadyPresentResponse: type: object properties: - locale: + message: type: string - enum: - - af - - am - - ar - - bg - - bn - - bs - - ca - - cs - - da - - de - - de-DE - - el - - en - - en-AU - - en-CA - - en-GB - - en-US - - es - - es-419 - - es-ES - - es-US - - et - - fa - - fi - - fil - - fr - - fr-BE - - fr-CA - - fr-FR - - fy - - gl - - gu - - ha - - he - - hi - - hr - - hu - - hy - - id - - is - - it - - it-IT - - ja - - jv - - ka - - kk - - km - - kn - - ko - - lt - - lv - - mk - - ml - - mn - - mr - - ms - - my - - nb - - ne - - nl - - nl-BE - - nl-NL - - nn - - 'no' - - pa - - pl - - pt - - pt-BR - - pt-PT - - ro - - ru - - sk - - sl - - sq - - sr - - sv - - sw - - ta - - te - - th - - tr - - uk - - ur - - uz - - vi - - zh - - zh-CN - - zh-HK - - zh-TW - - zu - description: >- - The locale to use when rendering the invitation email. See - [supported locales](/authkit/hosted-ui/localization). - example: en - CreateUserlandUserOrganizationMembershipDto: + description: A message indicating the entry already exists. + example: Entry already present in list + required: + - message + RedirectUri: type: object properties: - user_id: + object: + type: string + description: The object type. + const: redirect_uri + id: + type: string + description: The ID of the redirect URI. + example: ruri_01EHZNVPK3SFK441A1RGBFSHRT + uri: type: string - description: The ID of the [user](/reference/authkit/user). - example: user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E - organization_id: + description: The redirect URI. + example: https://example.com/callback + default: + type: boolean + description: Whether this is the default redirect URI. + example: true + created_at: type: string - description: >- - The ID of the [organization](/reference/organization) which the user - belongs to. - example: org_01E4ZCR3C56J083X43JQXF3JK5 - role_slug: + description: The timestamp when the redirect URI was created. + example: '2026-01-15T12:00:00.000Z' + updated_at: type: string - description: >- - A single role identifier. Defaults to `member` or the explicit - default role. Mutually exclusive with `role_slugs`. - example: admin - x-mutually-exclusive-with: - - role_slugs - role_slugs: - description: >- - An array of role identifiers. Limited to one role when Multiple - Roles is disabled. Mutually exclusive with `role_slug`. - example: - - admin - x-mutually-exclusive-with: - - role_slug - type: array - items: - type: string + description: The timestamp when the redirect URI was last updated. + example: '2026-01-15T12:00:00.000Z' required: - - user_id - - organization_id - UpdateUserlandUserOrganizationMembershipDto: + - object + - id + - uri + - default + - created_at + - updated_at + UserlandUserAuthenticationFactorList: type: object properties: - role_slug: + object: type: string - description: >- - A single role identifier. Defaults to `member` or the explicit - default role. Mutually exclusive with `role_slugs`. - example: admin - x-mutually-exclusive-with: - - role_slugs - role_slugs: - description: >- - An array of role identifiers. Limited to one role when Multiple - Roles is disabled. Mutually exclusive with `role_slug`. - example: - - admin - x-mutually-exclusive-with: - - role_slug + description: Indicates this is a list response. + const: list + data: type: array items: - type: string - CreateUserlandUserDto: + $ref: '#/components/schemas/AuthenticationFactor' + 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: auth_factor_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: auth_factor_01HXYZ987654321KJIHGFEDCBA + required: + - before + - after + description: Pagination cursors for navigating between pages of results. + required: + - object + - data + - list_metadata + UserlandUserAuthenticationFactorEnrollResponse: + type: object + properties: + authentication_factor: + $ref: '#/components/schemas/AuthenticationFactor' + authentication_challenge: + $ref: '#/components/schemas/AuthenticationChallenge' + description: >- + The [authentication + challenge](/reference/authkit/mfa/authentication-challenge) object + that is used to complete the authentication process. + required: + - authentication_factor + - authentication_challenge + MagicAuth: type: object properties: + object: + type: string + description: Distinguishes the Magic Auth object. + const: magic_auth + id: + type: string + description: The unique ID of the Magic Auth code. + example: magic_auth_01HWZBQZY2M3AMQW166Q22K88F + user_id: + type: string + description: The unique ID of the user. + example: user_01E4ZCR3C56J083X43JQXF3JK5 email: type: string description: The email address of the user. example: marcelina.davis@example.com - password: - type: - - string - - 'null' - description: >- - The password to set for the user. Mutually exclusive with - `password_hash` and `password_hash_type`. - example: strong_password_123! - x-mutually-exclusive-with: - - password_hash - - password_hash_type - password_hash: + expires_at: + format: date-time type: string - description: >- - The hashed password to set for the user. Mutually exclusive with - `password`. - example: $2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy - x-mutually-exclusive-with: - - password - password_hash_type: + description: The timestamp when the Magic Auth code expires. + example: '2026-01-15T12:00:00.000Z' + created_at: + format: date-time type: string - enum: &ref_4 - - bcrypt - - firebase-scrypt - - ssha - - scrypt - - pbkdf2 - - argon2 - description: >- - The algorithm originally used to hash the password, used when - providing a `password_hash`. - example: bcrypt - first_name: + 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' + code: + type: string + description: The code used to verify the Magic Auth code. + example: '123456' + required: + - object + - id + - user_id + - email + - expires_at + - created_at + - updated_at + - code + UserlandUserInvite: + type: object + properties: + object: + type: string + description: Distinguishes the invitation object. + const: invitation + id: + type: string + description: The unique ID of the invitation. + example: invitation_01E4ZCR3C56J083X43JQXF3JK5 + email: + type: string + description: The email address of the recipient. + example: marcelina.davis@example.com + state: + type: string + enum: + - pending + - accepted + - expired + - revoked + description: The state of the invitation. + example: pending + accepted_at: + format: date-time type: - string - 'null' - description: The first name of the user. - example: Marcelina - last_name: + description: >- + The timestamp when the invitation was accepted, or null if not yet + accepted. + example: null + revoked_at: + format: date-time type: - string - 'null' - description: The last name of the user. - example: Davis - email_verified: + description: >- + The timestamp when the invitation was revoked, or null if not + revoked. + example: null + expires_at: + format: date-time + type: string + description: The timestamp when the invitation expires. + example: '2026-01-15T12:00:00.000Z' + organization_id: type: - - boolean + - string - 'null' - description: Whether the user's email has been verified. - example: true - metadata: + description: >- + The ID of the [organization](/reference/organization) that the + recipient will join. + example: org_01E4ZCR3C56J083X43JQXF3JK5 + inviter_user_id: type: - - object + - string - 'null' - additionalProperties: *ref_2 - maxProperties: 50 - example: &ref_5 - timezone: America/New_York - description: Object containing metadata key/value pairs associated with the user. - propertyNames: - maxLength: 40 - external_id: + description: The ID of the user who invited the recipient, if provided. + example: user_01HYGBX8ZGD19949T3BM4FW1C3 + accepted_user_id: type: - string - 'null' - maxLength: 128 - description: The external ID of the user. - example: f1ffa2b2-c20b-4d39-be5c-212726e11222 + description: The ID of the user who accepted the invitation, once accepted. + example: null + 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' + token: + type: string + description: The token used to accept the invitation. + example: Z1uX3RbwcIl5fIGJJJCXXisdI + accept_invitation_url: + type: string + description: The URL where the recipient can accept the invitation. + example: >- + https://your-app.com/invite?invitation_token=Z1uX3RbwcIl5fIGJJJCXXisdI required: + - object + - id - email - UpdateUserlandUserDto: + - state + - accepted_at + - revoked_at + - expires_at + - organization_id + - inviter_user_id + - accepted_user_id + - created_at + - updated_at + - token + - accept_invitation_url + UserlandUserOrganizationMembership: type: object properties: - email: + object: + type: string + description: Distinguishes the organization membership object. + const: organization_membership + id: + type: string + description: The unique ID of the organization membership. + example: om_01HXYZ123456789ABCDEFGHIJ + user_id: + type: string + description: The ID of the user. + example: user_01EHQTV6MWP9P1F4ZXGXMC8ABB + organization_id: + type: string + description: The ID of the organization which the user belongs to. + example: org_01EHZNVPK3SFK441A1RGBFSHRT + status: + type: string + enum: + - active + - inactive + - pending + description: >- + The status of the organization membership. One of `active`, + `inactive`, or `pending`. + example: active + directory_managed: + type: boolean + description: >- + Whether this organization membership is managed by a directory sync + connection. + example: false + organization_name: + type: string + description: The name of the organization which the user belongs to. + example: Acme Corp + custom_attributes: + type: object + additionalProperties: {} + description: >- + An object containing IdP-sourced attributes from the linked + [Directory User](/reference/directory-sync/directory-user) or [SSO + Profile](/reference/sso/profile). Directory User attributes take + precedence when both are linked. + example: + department: Engineering + title: Developer Experience Engineer + location: Brooklyn + 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' + role: + $ref: '#/components/schemas/SlimRole' + description: The primary role assigned to the user within the organization. + required: + - object + - id + - user_id + - organization_id + - status + - directory_managed + - created_at + - updated_at + - role + UserlandUser: + type: object + properties: + object: + type: string + description: Distinguishes the user object. + const: user + id: type: string - description: The email address of the user. - example: marcelina.davis@example.com + description: The unique ID of the user. + example: user_01E4ZCR3C56J083X43JQXF3JK5 first_name: - type: string + type: + - string + - 'null' description: The first name of the user. example: Marcelina last_name: - type: string + type: + - string + - 'null' description: The last name of the user. example: Davis + profile_picture_url: + type: + - string + - 'null' + description: A URL reference to an image representing the user. + example: https://workoscdn.com/images/v1/123abc + email: + type: string + description: The email address of the user. + example: marcelina.davis@example.com email_verified: type: boolean description: Whether the user's email has been verified. example: true - password: - type: string - description: The password to set for the user. - example: strong_password_123! - password_hash: - type: string - description: >- - The hashed password to set for the user. Mutually exclusive with - `password`. - example: $2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy - x-mutually-exclusive-with: - - password - password_hash_type: - type: string - enum: *ref_4 - description: >- - The algorithm originally used to hash the password, used when - providing a `password_hash`. - example: bcrypt - metadata: + external_id: type: - - object + - string - 'null' - additionalProperties: *ref_2 - maxProperties: 50 - example: *ref_5 + description: The external ID of the user. + example: f1ffa2b2-c20b-4d39-be5c-212726e11222 + metadata: + type: object + additionalProperties: + type: string + maxLength: 600 description: Object containing metadata key/value pairs associated with the user. + example: + timezone: America/New_York propertyNames: maxLength: 40 - external_id: + maxProperties: 50 + last_sign_in_at: + format: date-time type: - string - 'null' - maxLength: 128 - description: The external ID of the user. - example: f1ffa2b2-c20b-4d39-be5c-212726e11222 + description: The timestamp when the user last signed in. + example: '2025-06-25T19:07:33.155Z' locale: type: - string - 'null' description: The user's preferred locale. example: en-US - VerifyEmailAddressDto: + 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 + - first_name + - last_name + - profile_picture_url + - email + - email_verified + - external_id + - last_sign_in_at + - created_at + - updated_at + description: The user object. + UserlandUserList: type: object properties: - code: + object: type: string - description: The one-time email verification code. - example: '123456' + description: Indicates this is a list response. + const: list + data: + type: array + items: + $ref: '#/components/schemas/UserlandUser' + 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: user_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: user_01HXYZ987654321KJIHGFEDCBA + required: + - before + - after + description: Pagination cursors for navigating between pages of results. required: - - code - CreatePasswordResetTokenDto: + - object + - data + - list_metadata + EmailVerification: type: object properties: + object: + type: string + description: Distinguishes the email verification object. + const: email_verification + id: + type: string + description: The unique ID of the email verification code. + example: email_verification_01E4ZCR3C56J083X43JQXF3JK5 + user_id: + type: string + description: The unique ID of the user. + example: user_01E4ZCR3C56J083X43JQXF3JK5 email: type: string - description: The email address of the user requesting a password reset. + description: The email address of the user. example: marcelina.davis@example.com + expires_at: + format: date-time + type: string + description: The timestamp when the email verification code expires. + example: '2026-01-15T12:00:00.000Z' + 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' + code: + type: string + description: The code used to verify the email. + example: '123456' required: + - object + - id + - user_id - email - CreatePasswordResetDto: + - expires_at + - created_at + - updated_at + - code + SendVerificationEmailResponse: type: object properties: - token: - type: string - description: The password reset token. - example: Z1Y2X3W4V5U6T7S8R9Q0P1O2N3 - new_password: - type: string - description: The new password to set for the user. - example: strong_password_123! + user: + $ref: '#/components/schemas/UserlandUser' + description: The user to whom the verification email was sent. required: - - token - - new_password - UserlandRevokeSessionDto: + - user + VerifyEmailResponse: type: object properties: - session_id: + user: + $ref: '#/components/schemas/UserlandUser' + description: The user whose email was verified. + required: + - user + PasswordReset: + type: object + properties: + object: type: string - description: >- - The ID of the session to revoke. This can be extracted from the - `sid` claim of the access token. - example: session_01H93ZY4F80QPBEZ1R5B2SHQG8 - return_to: + description: Distinguishes the password reset object. + const: password_reset + id: type: string - description: The URL to redirect the user to after session revocation. - example: https://example.com + description: The unique ID of the password reset object. + example: password_reset_01E4ZCR3C56J083X43JQXF3JK5 + user_id: + type: string + description: The unique ID of the user. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + email: + type: string + description: The email address of the user. + example: marcelina.davis@example.com + expires_at: + format: date-time + type: string + description: The timestamp when the password reset token expires. + example: '2026-01-15T12:00:00.000Z' + created_at: + format: date-time + type: string + description: The timestamp when the password reset token was created. + example: '2026-01-15T12:00:00.000Z' + password_reset_token: + type: string + description: The token used to reset the password. + example: Z1uX3RbwcIl5fIGJJJCXXisdI + password_reset_url: + type: string + description: The URL where the user can reset their password. + example: https://your-app.com/reset-password?token=Z1uX3RbwcIl5fIGJJJCXXisdI required: - - session_id - CreateWebhookEndpointDto: + - object + - id + - user_id + - email + - expires_at + - created_at + - password_reset_token + - password_reset_url + ResetPasswordResponse: type: object properties: - endpoint_url: - type: string - description: The HTTPS URL where webhooks will be sent. - example: https://example.com/webhooks - events: - description: The events that the Webhook Endpoint is subscribed to. - example: - - user.created - - dsync.user.created - type: array - items: - type: string + user: + $ref: '#/components/schemas/UserlandUser' + description: The user whose password was reset. required: - - endpoint_url - - events - WidgetSessionTokenDto: + - user + UserlandAuthenticateResponse: type: object properties: + user: + $ref: '#/components/schemas/UserlandUser' + description: The corresponding [user](/reference/authkit/user) object. organization_id: type: string - description: The ID of the organization to scope the widget session to. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - user_id: + description: The ID of the organization the user selected to sign in to. + example: org_01H945H0YD4F97JN9MATX7BYAG + authkit_authorization_code: type: string - description: The ID of the user to issue the widget session token for. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - scopes: - type: array - description: The scopes to grant the widget session. - items: - type: string - enum: - - widgets:users-table:manage - - widgets:domain-verification:manage - - widgets:sso:manage - - widgets:api-keys:manage - - widgets:dsync:manage - - widgets:audit-log-streaming:manage - example: - - widgets:users-table:manage + description: >- + An authorization code that can be exchanged for tokens by a + different application. + example: authkit_authz_code_abc123 + access_token: + type: string + description: A JWT containing information about the current session. + example: eyJhb.nNzb19vaWRjX2tleV9.lc5Uk4yWVk5In0 + refresh_token: + type: string + description: >- + [Exchange this + token](/reference/authkit/authentication/refresh-token) for a new + access token. + example: yAjhKk123NLIjdrBdGZPf8pLIDvK + authentication_method: + type: string + enum: + - SSO + - Password + - Passkey + - AppleOAuth + - BitbucketOAuth + - CrossAppAuth + - DiscordOAuth + - ExternalAuth + - GitHubOAuth + - GitLabOAuth + - GoogleOAuth + - IntuitOAuth + - LinkedInOAuth + - MicrosoftOAuth + - SalesforceOAuth + - SlackOAuth + - VercelMarketplaceOAuth + - VercelOAuth + - XeroOAuth + - MagicAuth + - Impersonation + - MigratedSession + description: The authentication method used to initiate the session. + example: SSO + impersonator: + type: object + properties: + email: + type: string + description: >- + The email address of the WorkOS Dashboard user who is + impersonating the user. + example: admin@foocorp.com + reason: + type: + - string + - 'null' + description: >- + The justification the impersonator gave for impersonating the + user. + example: Investigating an issue with the customer's account. + required: + - email + - reason + description: >- + Information about the impersonator if this session was created via + impersonation. + oauth_tokens: + type: object + properties: + provider: + type: string + description: The OAuth provider used for authentication. + example: GoogleOAuth + refresh_token: + type: string + description: The refresh token from the OAuth provider. + example: 1//04g... + access_token: + type: string + description: The access token from the OAuth provider. + example: ya29.a0ARrdaM... + expires_at: + type: number + description: The timestamp at which the access token expires. + example: 1735141800 + scopes: + type: array + items: + type: string + description: A list of OAuth scopes for which the access token is authorized. + example: + - profile + - email + - openid + required: + - provider + - refresh_token + - access_token + - expires_at + - scopes + description: The OAuth tokens from the identity provider, if applicable. required: - - organization_id - TokenQueryDto: + - user + - access_token + - refresh_token + DeviceAuthorizationResponse: type: object properties: - client_id: + device_code: type: string - description: The client ID of the WorkOS environment. - example: client_01HZBC6N1EB1ZY7KG32X - client_secret: + description: The device verification code. + example: CVE2wOfIFK4vhmiDBntpX9s8KT2f0qngpWYL0LGy9HxYgBRXUKIUkZB9BgIFho5h + user_code: type: string - description: The client secret of the WorkOS environment. - example: sk_example_123456789 - code: + description: The end-user verification code. + example: BCDF-GHJK + verification_uri: type: string - description: The authorization code received from the authorization callback. - example: authorization_code_value - grant_type: + format: uri + description: The end-user verification URI. + example: https://authkit_domain/device + verification_uri_complete: type: string - description: The grant type for the token request. - example: authorization_code - const: authorization_code + format: uri + description: Verification URI that includes the user code. + example: https://authkit_domain/device?user_code=BCDF-GHJK + expires_in: + type: number + description: Lifetime in seconds of the codes. + example: 300 + interval: + type: number + description: Minimum polling interval in seconds. + example: 5 required: - - client_id - - client_secret - - code - - grant_type - AuditLogExportJson: + - device_code + - user_code + - verification_uri + - expires_in + WebhookEndpointJson: type: object properties: object: type: string - description: Distinguishes the Audit Log Export object. - example: audit_log_export - const: audit_log_export + description: Distinguishes the Webhook Endpoint object. + const: webhook_endpoint id: type: string - description: The unique ID of the Audit Log Export. - example: audit_log_export_01GBZK5MP7TD1YCFQHFR22180V - state: + description: Unique identifier of the Webhook Endpoint. + example: we_0123456789 + endpoint_url: + type: string + description: The URL to which webhooks are sent. + example: https://example.com/webhooks + secret: + type: string + description: The secret used to sign webhook payloads. + example: whsec_0FWAiVGkEfGBqqsJH4aNAGBJ4 + status: type: string enum: - - pending - - ready - - error - description: 'The state of the export. Possible values: pending, ready, error.' - example: ready - url: - type: - - string - - 'null' - description: >- - A URL to the CSV file. Only defined when the Audit Log Export is - ready. - example: https://exports.audit-logs.com/audit-log-exports/export.csv + - enabled + - disabled + description: Whether the Webhook Endpoint is enabled or disabled. + example: enabled + events: + type: array + items: + type: string + description: The events that the Webhook Endpoint is subscribed to. + example: + - user.created + - dsync.user.created created_at: format: date-time type: string @@ -25293,200 +20246,343 @@ components: required: - object - id - - state + - endpoint_url + - secret + - status + - events - created_at - updated_at - AuditLogsRetentionJson: + WebhookEndpointList: type: object properties: - retention_period_in_days: + object: + type: string + description: Indicates this is a list response. + const: list + data: + type: array + items: + $ref: '#/components/schemas/WebhookEndpointJson' + 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: we_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: we_01HXYZ987654321KJIHGFEDCBA + required: + - before + - after + description: Pagination cursors for navigating between pages of results. + required: + - object + - data + - list_metadata + WidgetSessionTokenResponse: + type: object + properties: + token: + type: string + description: The widget session token. + example: eyJhbGciOiJSUzI1NiIsImtpZCI6InNlc3Npb24... + required: + - token + SsoAuthorizeUrlResponse: + type: object + properties: + url: + type: string + format: uri + description: An OAuth 2.0 authorization URL. + example: >- + https://accounts.google.com/o/oauth2/v2/auth?client_id=example&redirect_uri=https%3A%2F%2Fapi.workos.com%2Fsso%2Fcallback&response_type=code&scope=openid%20profile%20email + required: + - url + Profile: + type: object + properties: + object: + type: string + description: Distinguishes the profile object. + example: profile + const: profile + id: + type: string + description: Unique identifier of the profile. + example: prof_01DMC79VCBZ0NY2099737PSVF1 + organization_id: type: - - number + - string + - 'null' + description: The ID of the organization the user belongs to. + example: org_01EHQMYV6MBK39QC5PZXHY59C3 + connection_id: + type: string + description: The ID of the SSO connection used for authentication. + example: conn_01E4ZCR3C56J083X43JQXF3JK5 + connection_type: + type: string + enum: + - Pending + - ADFSSAML + - AdpOidc + - AppleOAuth + - Auth0Migration + - Auth0SAML + - AzureSAML + - BitbucketOAuth + - CasSAML + - ClassLinkSAML + - CleverOIDC + - CloudflareSAML + - CyberArkSAML + - DiscordOAuth + - DuoSAML + - EntraIdOIDC + - GenericOIDC + - GenericSAML + - GitHubOAuth + - GitLabOAuth + - GoogleOAuth + - GoogleOIDC + - GoogleSAML + - IntuitOAuth + - JumpCloudSAML + - KeycloakSAML + - LastPassSAML + - LinkedInOAuth + - LoginGovOidc + - MagicLink + - MicrosoftOAuth + - MiniOrangeSAML + - NetIqSAML + - OktaOIDC + - OktaSAML + - OneLoginSAML + - OracleSAML + - PingFederateSAML + - PingOneSAML + - RipplingSAML + - SalesforceSAML + - ShibbolethGenericSAML + - ShibbolethSAML + - SimpleSamlPhpSAML + - SalesforceOAuth + - SlackOAuth + - TestIdp + - VercelMarketplaceOAuth + - VercelOAuth + - VMwareSAML + - XeroOAuth + description: The type of SSO connection. + example: GoogleOAuth + idp_id: + type: string + description: The user's unique identifier from the identity provider. + example: '103456789012345678901' + email: + type: string + description: The user's email address. + example: todd@example.com + first_name: + type: + - string + - 'null' + description: The user's first name. + example: Todd + last_name: + type: + - string - 'null' + description: The user's last name. + example: Rundgren + role: description: >- - The number of days Audit Log events will be retained before being - permanently deleted. Valid values are 30 and 365. - example: 30 + The role assigned to the user within the organization, if + applicable. + oneOf: + - $ref: '#/components/schemas/SlimRole' + - type: 'null' + groups: + type: array + items: + type: string + description: >- + The groups the user belongs to, as returned by the identity + provider. + example: + - Engineering + - Admins + custom_attributes: + type: object + additionalProperties: {} + description: >- + Custom attribute mappings defined for the connection, returned as + key-value pairs. + raw_attributes: + type: object + additionalProperties: {} + description: >- + The complete set of raw attributes returned by the identity + provider. required: - - retention_period_in_days - AuditLogActionJson: + - object + - id + - organization_id + - connection_id + - connection_type + - idp_id + - email + - first_name + - last_name + - raw_attributes + description: The user profile returned by the identity provider. + SsoTokenResponse: type: object properties: - object: + token_type: type: string - description: Distinguishes the Audit Log Action object. - example: audit_log_action - const: audit_log_action - name: + description: The type of token issued. + const: Bearer + access_token: type: string - description: Identifier of what action was taken. - example: user.viewed_invoice - schema: + description: >- + An access token that can be exchanged for a user profile. Access + tokens are short-lived — see the `expires_in` field for the exact + lifetime. + example: eyJhbGciOiJSUzI1NiIsImtpZCI6InNzby... + expires_in: + type: number + description: The lifetime of the access token in seconds. + example: 600 + profile: + $ref: '#/components/schemas/Profile' + oauth_tokens: type: object properties: - object: + provider: + type: string + description: The OAuth provider used for authentication. + example: GoogleOAuth + refresh_token: type: string - description: Distinguishes the Audit Log Schema object. - example: audit_log_schema - const: audit_log_schema - version: + description: The refresh token from the OAuth provider. + example: 1//04g... + access_token: + type: string + description: The access token from the OAuth provider. + example: ya29.a0ARrdaM... + expires_at: type: number - description: The version of the schema. - example: 1 - actor: - type: object - properties: - metadata: - type: object - additionalProperties: {} - description: The JSON Schema definition for actor metadata. - required: - - metadata - description: The metadata schema for the actor. - example: - metadata: - type: object - properties: - role: - type: string - targets: + description: The timestamp at which the access token expires. + example: 1735141800 + scopes: type: array items: - type: object - properties: - type: - type: string - description: The type of the target resource. - example: invoice - metadata: - type: object - additionalProperties: {} - description: Additional data associated with the event or entity. - example: - type: object - properties: - cost: - type: number - required: - - type - description: The list of targets for the schema. - example: - - type: invoice - metadata: - type: object - properties: - status: - type: string - metadata: - type: object - additionalProperties: {} - description: Additional data associated with the event or entity. + type: string + description: A list of OAuth scopes for which the access token is authorized. example: - type: object - properties: - transactionId: - type: string - created_at: - format: date-time - type: string - description: The timestamp when the Audit Log Schema was created. - example: '2026-01-15T12:00:00.000Z' + - profile + - email + - openid required: - - object - - version - - targets - - created_at - description: The schema associated with the action. - created_at: - format: date-time + - provider + - refresh_token + - access_token + - expires_at + - scopes + description: OAuth tokens issued by the identity provider, if available. + required: + - token_type + - access_token + - expires_in + - profile + SsoLogoutAuthorizeResponse: + type: object + properties: + logout_url: type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - updated_at: - format: date-time + description: >- + The URL to redirect the user to in order to log out ([Logout + Redirect](/reference/sso/logout) endpoint ready to use). + example: https://auth.workos.com/sso/logout?token=eyJhbGciOiJSUzI1NiJ9 + logout_token: type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' + description: >- + The logout token to be used in the [Logout + Redirect](/reference/sso/logout) endpoint. + example: >- + eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwcm9maWxlX2lkIjoicHJvZl8wMUdXUTFHMEgyRk02QVNFRjBIUzEzSENXOS0zMDRrZzAzZyIsImV4cCI6IjE1MTYyMzkwMjIifQ.Wru9Qlnf5DpohtGCKhZU4cVOd3zpiu7QQ-XEX--5A_4 required: - - object - - name - - schema - - created_at - - updated_at - AuditLogSchemaJson: + - logout_url + - logout_token + JwksResponse: type: object properties: - object: - type: string - description: Distinguishes the Audit Log Schema object. - example: audit_log_schema - const: audit_log_schema - version: - type: number - description: The version of the schema. - example: 1 - actor: - type: object - properties: - metadata: - type: object - additionalProperties: {} - description: The JSON Schema definition for actor metadata. - required: - - metadata - description: The metadata schema for the actor. - example: - metadata: - type: object - properties: - role: - type: string - targets: + keys: type: array items: type: object properties: - type: + alg: type: string - description: The type of the target resource. - example: invoice - metadata: - type: object - additionalProperties: {} - description: Additional data associated with the event or entity. + description: Algorithm. + const: RS256 + kty: + type: string + description: Key type. + const: RSA + use: + type: string + description: Key use (signature). + const: sig + x5c: + type: array + items: + type: string + description: X.509 certificate chain. example: - type: object - properties: - cost: - type: number - required: - - type - description: The list of targets for the schema. - example: - - type: invoice - metadata: - type: object - properties: - status: - type: string - metadata: - type: object - additionalProperties: {} - description: Additional data associated with the event or entity. - example: - type: object - properties: - transactionId: + - MIIDQjCCAiqgAwIBAgIGATz/FuLiMA0GCSqGSIb3DQEBCwUA... + 'n': type: string - created_at: - format: date-time - type: string - description: The timestamp when the Audit Log Schema was created. - example: '2026-01-15T12:00:00.000Z' + description: RSA modulus. + example: 0vx7agoebGc...eKnNs + e: + type: string + description: RSA exponent. + example: AQAB + kid: + type: string + description: Key ID. + example: key_01HXYZ123456789ABCDEFGHIJ + x5t#S256: + type: string + description: X.509 certificate SHA-256 thumbprint. + example: ZjQzYjI0OT...NmNjU0 + required: + - alg + - kty + - use + - x5c + - 'n' + - e + - kid + - x5t#S256 + description: The public keys used for verifying access tokens. required: - - object - - version - - targets - - created_at + - keys security: - bearer: []