openapi: 3.1.1 paths: /api_keys/validations: post: description: Validate an API key value and return the API key object if valid. operationId: ApiKeysController_validateApiKey parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ValidateApiKeyDto' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiKeyValidationResponse' '401': description: Unauthorized '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Validate API key tags: - api_keys /api_keys/{id}: delete: description: >- Permanently deletes an API key. This action cannot be undone. Once deleted, any requests using this API key will fail authentication. operationId: ApiKeysController_delete parameters: - name: id required: true in: path description: The unique ID of the API key. schema: type: string example: api_key_01EHZNVPK3SFK441A1RGBFSHRT 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 summary: Delete an API key tags: - api_keys /api_keys/{id}/expire: post: description: >- Expire an API key immediately, schedule a future expiration, or clear a scheduled future expiration. operationId: ApiKeysController_expire parameters: - name: id required: true in: path description: The unique ID of the API key. schema: type: string example: api_key_01EHZNVPK3SFK441A1RGBFSHRT requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/ExpireApiKeyDto' examples: immediateExpiration: summary: Expire immediately value: {} scheduleExpiration: summary: Schedule an expiration value: expires_at: '2030-01-01T00:00:00.000Z' clearExpiration: summary: Clear a scheduled expiration value: expires_at: null responses: '200': content: application/json: schema: $ref: '#/components/schemas/ApiKey' example: object: api_key id: api_key_01EHZNVPK3SFK441A1RGBFSHRT owner: type: organization id: org_01EHZNVPK3SFK441A1RGBFSHRT name: Production API Key obfuscated_value: sk_...3456 last_used_at: null expires_at: '2030-01-01T00:00:00.000Z' permissions: - posts:read - posts:write created_at: '2026-01-15T12:00:00.000Z' updated_at: '2026-01-15T12:00:00.000Z' description: OK '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'API Key not found: ''api_key_01EHZNVPK3SFK441A1RGBFSHRT''.' required: - message x-inline-with-overrides: true '409': description: Conflict content: application/json: schema: type: object properties: code: type: string description: The error code identifying the type of error. example: api_key_already_expired const: api_key_already_expired message: type: string description: A human-readable description of the error. example: API key is already expired required: - code - message x-inline-with-overrides: true '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Expire an API key tags: - api_keys /audit_logs/actions: get: description: Get a list of all Audit Log actions in the current environment. operationId: AuditLogValidatorsController_list parameters: - name: before required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. 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: integer - name: order required: false in: query description: Order the results by the creation time. schema: $ref: '#/components/schemas/PaginationOrder' 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: ala_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: ala_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/AuditLogActionJson' '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: List Actions tags: - audit-logs /audit_logs/actions/{actionName}/schemas: post: description: >- Creates a new Audit Log schema used to validate the payload of incoming Audit Log Events. If the `action` does not exist, it will also be created. operationId: AuditLogValidatorVersionsController_create parameters: - name: actionName required: true in: path description: The name of the Audit Log action. schema: example: user.logged_in type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AuditLogSchemaDto' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/AuditLogSchemaJson' '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Create Schema tags: - audit-logs get: description: >- Get a list of all schemas for the Audit Logs action identified by `:name`. operationId: AuditLogValidatorVersionsController_schemas parameters: - name: actionName required: true in: path description: The name of the Audit Log action. schema: example: user.logged_in 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: integer - name: order required: false in: query description: Order the results by the creation time. schema: $ref: '#/components/schemas/PaginationOrder' 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: als_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: als_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/AuditLogSchemaJson' '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: List Schemas tags: - audit-logs /audit_logs/events: post: description: >- Create an Audit Log Event. This API supports idempotency which guarantees that performing the same operation multiple times will have the same result as if the operation were performed only once. This is handy in situations where you may need to retry a request due to a failure or prevent accidental duplicate requests from creating more than one resource. To achieve idempotency, you can add `Idempotency-Key` request header to a Create Event request with a unique string as the value. Each subsequent request matching this unique string will return the same response. We suggest using [v4 UUIDs](https://en.wikipedia.org/wiki/Universally_unique_identifier) for idempotency keys to avoid collisions. Idempotency keys expire after 24 hours. The API will generate a new response if you submit a request with an expired key. operationId: AuditLogEventsController_create parameters: - name: idempotency-key in: header description: >- A unique string to prevent duplicate requests. Each subsequent request matching this unique string will return the same response. We suggest using v4 UUIDs. Keys expire after 24 hours. required: false schema: type: string example: 884793cd-bef4-46cf-8790-e3d4957a09ce requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AuditLogEventIngestionDto' responses: '200': content: application/json: schema: $ref: '#/components/schemas/AuditLogEventCreateResponse' example: success: true description: OK '400': content: application/json: schema: anyOf: - type: object properties: errors: type: array items: type: object properties: instancePath: type: string description: >- The JSON path to the invalid field in the event payload. example: /targets required: - instancePath description: The list of validation errors. message: type: string description: A human-readable description of the error. example: Invalid Audit Log event. code: type: string description: The error code identifying the type of error. example: invalid_audit_log_event required: - errors - message - code - type: object properties: message: type: string description: A human-readable description of the error. example: >- Organization not found: 'org_01EHQMYV6MBK39QC5PZXHY59C3'. required: - message example: message: Invalid Audit Log event. code: invalid_audit_log_event errors: - instancePath: /targets description: Bad Request '404': 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: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' description: Not Found '422': content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string description: The validation error code. example: required field: type: string description: The field that failed validation. example: event.action required: - code - field description: The list of validation errors. message: type: string description: A human-readable description of the error. example: Validation failed. required: - errors - message example: message: Validation failed. errors: - code: required field: event.action description: Unprocessable Entity '429': content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: Too many requests. code: type: string description: The error code identifying the type of error. example: rate_limit_exceeded required: - message - code example: message: Too many requests. code: rate_limit_exceeded description: '' summary: Create Event tags: - audit-logs /audit_logs/exports: post: description: >- Create an Audit Log Export. Exports are scoped to a single organization within a specified date range. operationId: AuditLogExportsController_exports parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AuditLogExportCreationDto' responses: '201': description: The created Audit Log Export object. content: application/json: schema: $ref: '#/components/schemas/AuditLogExportJson' example: object: audit_log_export id: audit_log_export_01GBZK5MP7TD1YCFQHFR22180V state: pending created_at: '2022-09-02T17:14:57.094Z' updated_at: '2022-09-02T17:14:57.094Z' '400': description: Invalid request parameters or date range. content: application/json: schema: anyOf: - 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 human-readable error messages describing the validation failures. example: - Invalid date range error: type: string description: The error type. example: Bad Request required: - message - error example: message: Invalid date range code: invalid_audit_log_export_range_date summary: Create Export tags: - audit-logs /audit_logs/exports/{auditLogExportId}: get: description: >- Get an Audit Log Export. The URL will expire after 10 minutes. If the export is needed again at a later time, refetching the export will regenerate the URL. operationId: AuditLogExportsController_export parameters: - name: auditLogExportId required: true in: path description: The unique ID of the Audit Log Export. schema: type: string example: audit_log_export_01GBZK5MP7TD1YCFQHFR22180V responses: '200': description: The Audit Log Export object. content: application/json: schema: $ref: '#/components/schemas/AuditLogExportJson' example: object: audit_log_export id: audit_log_export_01GBZK5MP7TD1YCFQHFR22180V state: ready url: https://exports.audit-logs.com/audit-log-exports/export.csv created_at: '2022-09-02T17:14:57.094Z' updated_at: '2022-09-02T17:14:57.094Z' '404': description: Audit Log Export 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 example: message: >- Audit Log Export not found: 'audit_log_export_01GBZK5MP7TD1YCFQHFR22180V'. summary: Get Export tags: - audit-logs /auth/challenges/{id}/verify: post: description: Verifies an Authentication Challenge. operationId: AuthenticationChallengesController_verify parameters: - name: id required: true in: path description: The unique ID of the Authentication Challenge. schema: type: string example: auth_challenge_01FVYZ5QM8N98T9ME5BCB2BBMJ requestBody: required: true content: application/json: schema: type: object properties: code: type: string description: The one-time code to verify. example: '123456' required: - code responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/AuthenticationChallengeVerifyResponse' '400': description: Bad Request content: application/json: schema: type: object properties: code: type: string description: The error code identifying the type of error. example: one_time_code_too_many_attempts const: one_time_code_too_many_attempts message: type: string description: A human-readable description of the error. example: Request could not be processed. required: - code - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Verify Challenge tags: - multi-factor-auth.challenges /auth/factors/enroll: post: description: >- Enrolls an Authentication Factor to be used as an additional factor of authentication. The returned ID should be used to create an authentication Challenge. operationId: AuthenticationFactorsController_create parameters: [] requestBody: required: true content: application/json: schema: type: object properties: type: type: string enum: - generic_otp - sms - totp description: The type of factor to enroll. example: totp phone_number: type: string description: Required when type is 'sms'. example: '+15555555555' totp_issuer: type: string description: Required when type is 'totp'. example: Foo Corp totp_user: type: string description: Required when type is 'totp'. example: alan.turing@example.com user_id: type: string description: The ID of the user to associate the factor with. example: user_01E4ZCR3C56J083X43JQXF3JK5 required: - type responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/AuthenticationFactorEnrolled' '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Enroll Factor tags: - multi-factor-auth /auth/factors/{id}: get: description: Gets an Authentication Factor. operationId: AuthenticationFactorsController_get parameters: - name: id required: true in: path description: The unique ID of the Factor. schema: type: string example: auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ responses: '200': content: application/json: schema: $ref: '#/components/schemas/AuthenticationFactor' example: object: authentication_factor id: auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ type: totp user_id: user_01E4ZCR3C56J083X43JQXF3JK5 totp: issuer: WorkOS user: user@example.com created_at: '2026-01-15T12:00:00.000Z' updated_at: '2026-01-15T12:00:00.000Z' description: OK '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Get Factor tags: - multi-factor-auth delete: description: Permanently deletes an Authentication Factor. It cannot be undone. operationId: AuthenticationFactorsController_delete parameters: - name: id required: true in: path description: The unique ID of the Factor. schema: type: string example: auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ responses: '200': description: OK '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 summary: Delete Factor tags: - multi-factor-auth /auth/factors/{id}/challenge: post: description: Creates a Challenge for an Authentication Factor. operationId: AuthenticationFactorsController_challenge parameters: - name: id required: true in: path description: The unique ID of the Authentication Factor to be challenged. schema: type: string example: auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ChallengeAuthenticationFactorDto' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/AuthenticationChallenge' '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Challenge Factor tags: - multi-factor-auth /authkit/oauth2/complete: post: description: >- Completes an external authentication flow and returns control to AuthKit. This endpoint is used with [Standalone Connect](/authkit/connect/standalone) to bridge your existing authentication system with the Connect OAuth API infrastructure. After successfully authenticating a user in your application, calling this endpoint will: - Create or update the user in AuthKit, using the given `id` as its `external_id`. - Return a `redirect_uri` your application should redirect to in order for AuthKit to complete the flow Users are automatically created or updated based on the `id` and `email` provided. If a user with the same `id` exists, their information is updated. Otherwise, a new user is created. If you provide a new `id` with an `email` that already belongs to an existing user, the request will fail with an error as email addresses are unique to a user. operationId: ExternalAuthController_completeLogin parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UserManagementLoginRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ExternalAuthCompleteResponse' '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: external_auth_session_already_completed const: external_auth_session_already_completed 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: error: type: string description: The HTTP error type. example: Bad Request message: type: string description: A human-readable description of the error. example: Claim "sub" is reserved and cannot be used. required: - error - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Complete external authentication tags: - workos-connect /authorization/organization_memberships/{organization_membership_id}/check: post: description: >- Check if an organization membership has a specific permission on a resource. Supports identification by resource_id OR by resource_external_id + resource_type_slug. operationId: AuthorizationController_check parameters: - name: organization_membership_id required: true in: path description: The ID of the organization membership to check. schema: type: string example: om_01HXYZ123456789ABCDEFGHIJ requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CheckAuthorizationDto' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AuthorizationCheck' '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Check authorization tags: - authorization x-mutually-exclusive-body-groups: &ref_3 resource_target: optional: false variants: by_id: - resource_id by_external_id: - resource_external_id - resource_type_slug /authorization/organization_memberships/{organization_membership_id}/resources: get: description: >- Returns all child resources of a parent resource where the organization membership has a specific permission. This is useful for resource discovery—answering "What projects can this user access in this workspace?" You must provide either `parent_resource_id` or both `parent_resource_external_id` and `parent_resource_type_slug` to identify the parent resource. operationId: AuthorizationController_listResourcesForMembership parameters: - name: organization_membership_id required: true in: path description: The ID of the organization membership. schema: type: string example: om_01HXYZ123456789ABCDEFGHIJ - name: before required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `before="obj_123"` to fetch a new batch of objects before `"obj_123"`. schema: example: xxx_01HXYZ123456789ABCDEFGHIJ type: string - name: after required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `after="obj_123"` to fetch a new batch of objects after `"obj_123"`. schema: example: xxx_01HXYZ987654321KJIHGFEDCBA type: string - name: limit required: false in: query description: >- Upper limit on the number of objects to return, between `1` and `100`. schema: minimum: 1 maximum: 100 default: 10 example: 10 type: integer - name: order required: false in: query description: >- Order the results by the creation time. Supported values are `"asc"` (ascending), `"desc"` (descending), and `"normal"` (descending with reversed cursor semantics where `before` fetches older records and `after` fetches newer records). schema: $ref: '#/components/schemas/PaginationOrder' - name: permission_slug required: true in: query description: >- The permission slug to filter by. Only child resources where the organization membership has this permission are returned. schema: type: string example: project:read - name: parent_resource_id required: false in: query description: >- The WorkOS ID of the parent resource. Provide this or both `parent_resource_external_id` and `parent_resource_type_slug`, but not both. Mutually exclusive with `parent_resource_type_slug` and `parent_resource_external_id`. schema: type: string example: authz_resource_01XYZ789 - name: parent_resource_type_slug required: false in: query description: >- The slug of the parent resource type. Must be provided together with `parent_resource_external_id`. Required with `parent_resource_external_id`. Mutually exclusive with `parent_resource_id`. schema: type: string example: project - name: parent_resource_external_id required: false in: query description: >- The application-specific external identifier of the parent resource. Must be provided together with `parent_resource_type_slug`. Required with `parent_resource_type_slug`. Mutually exclusive with `parent_resource_id`. schema: type: string example: external_project_123 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AuthorizationResourceList' '400': description: Bad Request content: application/json: schema: type: object properties: code: type: string description: The error code identifying the type of error. example: bad_request const: bad_request message: type: string description: A human-readable description of the error. example: Request could not be processed. required: - code - message '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: List resources for organization membership tags: - authorization x-mutually-exclusive-parameter-groups: parent_resource: optional: false variants: by_id: - parent_resource_id by_external_id: - parent_resource_type_slug - parent_resource_external_id /authorization/organization_memberships/{organization_membership_id}/resources/{resource_id}/permissions: get: description: >- Returns all permissions the organization membership effectively has on a resource, including permissions inherited through roles assigned to ancestor resources. operationId: AuthorizationController_listEffectivePermissions parameters: - name: organization_membership_id required: true in: path description: The ID of the organization membership. schema: type: string example: om_01HXYZ123456789ABCDEFGHIJ - name: resource_id required: true in: path description: The ID of the authorization resource. schema: type: string example: authz_resource_01HXYZ123456789ABCDEFGHIJ - name: before required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `before="obj_123"` to fetch a new batch of objects before `"obj_123"`. schema: example: xxx_01HXYZ123456789ABCDEFGHIJ type: string - name: after required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `after="obj_123"` to fetch a new batch of objects after `"obj_123"`. schema: example: xxx_01HXYZ987654321KJIHGFEDCBA type: string - name: limit required: false in: query description: >- Upper limit on the number of objects to return, between `1` and `100`. schema: minimum: 1 maximum: 100 default: 10 example: 10 type: integer - name: order required: false in: query description: >- Order the results by the creation time. Supported values are `"asc"` (ascending), `"desc"` (descending), and `"normal"` (descending with reversed cursor semantics where `before` fetches older records and `after` fetches newer records). schema: $ref: '#/components/schemas/PaginationOrder' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AuthorizationPermissionList' '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: List effective permissions for an organization membership on a resource tags: - authorization /authorization/organization_memberships/{organization_membership_id}/resources/{resource_type_slug}/{external_id}/permissions: get: description: >- Returns all permissions the organization membership effectively has on a resource identified by its external ID, including permissions inherited through roles assigned to ancestor resources. operationId: AuthorizationController_listEffectivePermissionsByExternalId parameters: - name: organization_membership_id required: true in: path description: The ID of the organization membership. schema: type: string example: om_01HXYZ123456789ABCDEFGHIJ - name: resource_type_slug required: true in: path description: The slug of the resource type. schema: type: string example: document - name: external_id required: true in: path description: An identifier you provide to reference the resource in your system. schema: type: string example: doc-456 - name: before required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `before="obj_123"` to fetch a new batch of objects before `"obj_123"`. schema: example: xxx_01HXYZ123456789ABCDEFGHIJ type: string - name: after required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `after="obj_123"` to fetch a new batch of objects after `"obj_123"`. schema: example: xxx_01HXYZ987654321KJIHGFEDCBA type: string - name: limit required: false in: query description: >- Upper limit on the number of objects to return, between `1` and `100`. schema: minimum: 1 maximum: 100 default: 10 example: 10 type: integer - name: order required: false in: query description: >- Order the results by the creation time. Supported values are `"asc"` (ascending), `"desc"` (descending), and `"normal"` (descending with reversed cursor semantics where `before` fetches older records and `after` fetches newer records). schema: $ref: '#/components/schemas/PaginationOrder' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AuthorizationPermissionList' '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: >- List effective permissions for an organization membership on a resource by external ID tags: - authorization /authorization/organization_memberships/{organization_membership_id}/role_assignments: get: description: >- List all role assignments for an organization membership. This returns all roles that have been assigned to the user on resources, including organization-level and sub-resource roles. operationId: AuthorizationRoleAssignmentsController_listRoleAssignments parameters: - name: organization_membership_id required: true in: path description: The ID of the organization membership. schema: type: string example: om_01HXYZ123456789ABCDEFGHIJ - name: before required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `before="obj_123"` to fetch a new batch of objects before `"obj_123"`. schema: example: xxx_01HXYZ123456789ABCDEFGHIJ type: string - name: after required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `after="obj_123"` to fetch a new batch of objects after `"obj_123"`. schema: example: xxx_01HXYZ987654321KJIHGFEDCBA type: string - name: limit required: false in: query description: >- Upper limit on the number of objects to return, between `1` and `100`. schema: minimum: 1 maximum: 100 default: 10 example: 10 type: integer - name: order required: false in: query description: >- Order the results by the creation time. Supported values are `"asc"` (ascending), `"desc"` (descending), and `"normal"` (descending with reversed cursor semantics where `before` fetches older records and `after` fetches newer records). schema: $ref: '#/components/schemas/PaginationOrder' - name: resource_id required: false in: query description: Filter assignments by the ID of the resource. schema: example: authz_resource_01HXYZ123456789ABCDEFGH type: string - name: resource_external_id required: false in: query description: Filter assignments by the external ID of the resource. schema: example: project-ext-456 type: string - name: resource_type_slug required: false in: query description: Filter assignments by the slug of the resource type. schema: example: project type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/UserRoleAssignmentList' '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: List role assignments tags: - authorization post: description: Assign a role to an organization membership on a specific resource. operationId: AuthorizationRoleAssignmentsController_assignRole parameters: - name: organization_membership_id required: true in: path description: The ID of the organization membership. schema: type: string example: om_01HXYZ123456789ABCDEFGHIJ requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AssignRoleDto' responses: '201': content: application/json: schema: $ref: '#/components/schemas/UserRoleAssignment' example: object: role_assignment id: role_assignment_01HXYZ123456789ABCDEFGH organization_membership_id: om_01HXYZ123456789ABCDEFGHIJ role: slug: editor resource: id: authz_resource_01HXYZ123456789ABCDEFGH external_id: project-ext-456 resource_type_slug: project created_at: '2026-01-15T12:00:00.000Z' updated_at: '2026-01-15T12:00:00.000Z' description: Created '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Assign a role tags: - authorization x-mutually-exclusive-body-groups: &ref_4 resource_target: optional: false variants: by_id: - resource_id by_external_id: - resource_external_id - resource_type_slug delete: description: Remove a role assignment by role slug and resource. operationId: AuthorizationRoleAssignmentsController_removeRoleByCriteria parameters: - name: organization_membership_id required: true in: path description: The ID of the organization membership. schema: type: string example: om_01HXYZ123456789ABCDEFGHIJ requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RemoveRoleDto' responses: '204': description: Role assignment removed successfully. '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Remove a role assignment tags: - authorization x-mutually-exclusive-body-groups: &ref_5 resource_target: optional: false variants: by_id: - resource_id by_external_id: - resource_external_id - resource_type_slug /authorization/organization_memberships/{organization_membership_id}/role_assignments/{role_assignment_id}: delete: description: Remove a role assignment using its ID. operationId: AuthorizationRoleAssignmentsController_removeRoleById parameters: - name: organization_membership_id required: true in: path description: The ID of the organization membership. schema: type: string example: om_01HXYZ123456789ABCDEFGHIJ - name: role_assignment_id required: true in: path description: The ID of the role assignment to remove. schema: type: string example: role_assignment_01HXYZ123456789ABCDEFGH responses: '204': description: Role assignment removed successfully. '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Remove a role assignment by ID tags: - authorization /authorization/organizations/{organizationId}/roles: post: description: Create a new custom role for this organization. operationId: AuthorizationOrganizationRolesController_create parameters: - name: organizationId required: true in: path description: The ID of the organization. schema: type: string example: org_01EHZNVPK3SFK441A1RGBFSHRT requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateOrganizationRoleDto' responses: '201': description: Created content: application/json: schema: type: object properties: slug: type: string description: A unique slug for the role. example: org-billing-admin object: type: string description: Distinguishes the role object. example: role const: role id: type: string description: Unique identifier of the role. example: role_01EHQMYV6MBK39QC5PZXHY59C3 name: type: string description: A descriptive name for the role. example: Billing Administrator description: type: - string - 'null' description: An optional description of the role. example: Can manage billing and invoices type: type: string enum: - EnvironmentRole - OrganizationRole description: >- Whether the role is scoped to the environment or an organization (custom role). example: OrganizationRole resource_type_slug: type: string description: The slug of the resource type the role is scoped to. example: organization permissions: type: array items: type: string description: The permission slugs assigned to the role. example: - posts:read - posts:write created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' updated_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' required: - slug - object - id - name - description - type - resource_type_slug - permissions - 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 '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '409': description: '' content: application/json: schema: type: object properties: code: type: string description: The error code identifying the type of error. example: organization_role_slug_conflict const: organization_role_slug_conflict message: type: string description: A human-readable description of the error. example: Request could not be processed. required: - code - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Create a custom role tags: - authorization get: description: >- Get a list of all roles that apply to an organization. This includes both environment roles and custom roles, returned in priority order. operationId: AuthorizationOrganizationRolesController_list parameters: - name: organizationId required: true in: path description: The ID of the organization. schema: type: string example: org_01EHZNVPK3SFK441A1RGBFSHRT responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RoleList' '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: List custom roles tags: - authorization /authorization/organizations/{organizationId}/roles/{slug}: get: description: >- Retrieve a role that applies to an organization by its slug. This can return either an environment role or a custom role. operationId: AuthorizationOrganizationRolesController_get parameters: - name: organizationId required: true in: path description: The ID of the organization. schema: type: string example: org_01EHZNVPK3SFK441A1RGBFSHRT - name: slug required: true in: path description: The slug of the role. schema: type: string example: org-billing-admin responses: '200': description: OK content: application/json: schema: type: object properties: slug: type: string description: A unique slug for the role. example: org-billing-admin object: type: string description: Distinguishes the role object. example: role const: role id: type: string description: Unique identifier of the role. example: role_01EHQMYV6MBK39QC5PZXHY59C3 name: type: string description: A descriptive name for the role. example: Billing Manager description: type: - string - 'null' description: An optional description of the role. example: Can view and export billing reports type: type: string enum: - EnvironmentRole - OrganizationRole description: >- Whether the role is scoped to the environment or an organization (custom role). example: OrganizationRole resource_type_slug: type: string description: The slug of the resource type the role is scoped to. example: organization permissions: type: array items: type: string description: The permission slugs assigned to the role. example: - posts:read - posts:write created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' updated_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' required: - slug - object - id - name - description - type - resource_type_slug - permissions - created_at - updated_at x-inline-with-overrides: true '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Get a custom role tags: - authorization patch: description: >- Update an existing custom role. Only the fields provided in the request body will be updated. operationId: AuthorizationOrganizationRolesController_update parameters: - name: organizationId required: true in: path description: The ID of the organization. schema: type: string example: org_01EHZNVPK3SFK441A1RGBFSHRT - name: slug required: true in: path description: The slug of the role. schema: type: string example: org-billing-admin requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateOrganizationRoleDto' responses: '200': description: OK content: application/json: schema: type: object properties: slug: type: string description: A unique slug for the role. example: org-billing-admin object: type: string description: Distinguishes the role object. example: role const: role id: type: string description: Unique identifier of the role. example: role_01EHQMYV6MBK39QC5PZXHY59C3 name: type: string description: A descriptive name for the role. example: Finance Administrator description: type: - string - 'null' description: An optional description of the role. example: Can manage all financial operations type: type: string enum: - EnvironmentRole - OrganizationRole description: >- Whether the role is scoped to the environment or an organization (custom role). example: OrganizationRole resource_type_slug: type: string description: The slug of the resource type the role is scoped to. example: organization permissions: type: array items: type: string description: The permission slugs assigned to the role. example: - posts:read - posts:write created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' updated_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' required: - slug - object - id - name - description - type - resource_type_slug - permissions - 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 '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Update a custom role tags: - authorization delete: description: Delete an existing custom role. operationId: AuthorizationOrganizationRolesController_delete parameters: - name: organizationId required: true in: path description: The ID of the organization. schema: type: string example: org_01EHZNVPK3SFK441A1RGBFSHRT - name: slug required: true in: path description: The slug of the role. schema: type: string example: org-admin responses: '204': description: No Content '400': description: Bad Request content: application/json: schema: type: object properties: code: type: string description: The error code identifying the type of error. example: bad_request const: bad_request message: type: string description: A human-readable description of the error. example: Request could not be processed. required: - code - message '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '409': description: '' content: application/json: schema: oneOf: - type: object properties: code: type: string description: The error code identifying the type of error. example: role_has_assignments const: role_has_assignments 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: role_has_group_role_mappings const: role_has_group_role_mappings message: type: string description: A human-readable description of the error. example: Request could not be processed. required: - code - message summary: Delete a custom role tags: - authorization /authorization/organizations/{organizationId}/roles/{slug}/permissions: put: description: Replace all permissions on a custom role with the provided list. operationId: AuthorizationOrganizationRolePermissionsController_setPermissions parameters: - name: organizationId required: true in: path description: The ID of the organization. schema: type: string example: org_01EHZNVPK3SFK441A1RGBFSHRT - name: slug required: true in: path description: The slug of the role. schema: type: string example: org-admin requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SetRolePermissionsDto' responses: '200': description: OK 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 (custom role). example: OrganizationRole resource_type_slug: type: string description: The slug of the resource type the role is scoped to. example: organization permissions: type: array items: type: string description: The permission slugs assigned to the role. example: - billing:read - billing:write - invoices:manage - reports:view 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 x-inline-with-overrides: true '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Set permissions for a custom role tags: - authorization post: description: >- Add a single permission to a custom role. If the permission is already assigned to the role, this operation has no effect. operationId: AuthorizationOrganizationRolePermissionsController_addPermission parameters: - name: organizationId required: true in: path description: The ID of the organization. schema: type: string example: org_01EHZNVPK3SFK441A1RGBFSHRT - name: slug required: true in: path description: The slug of the role. schema: type: string example: org-admin requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AddRolePermissionDto' responses: '200': description: OK 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 (custom role). example: OrganizationRole resource_type_slug: type: string description: The slug of the resource type the role is scoped to. example: organization permissions: type: array items: type: string description: The permission slugs assigned to the role. example: - reports:export 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 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 '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Add a permission to a custom role tags: - authorization /authorization/organizations/{organizationId}/roles/{slug}/permissions/{permissionSlug}: delete: description: Remove a single permission from a custom role by its slug. operationId: AuthorizationOrganizationRolePermissionsController_removePermission parameters: - name: organizationId required: true in: path description: The ID of the organization. schema: type: string example: org_01EHZNVPK3SFK441A1RGBFSHRT - name: slug required: true in: path description: The slug of the role. schema: type: string example: org-admin - name: permissionSlug required: true in: path description: The slug of the permission to remove. schema: type: string example: documents:read responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Role' '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Remove a permission from a custom role tags: - authorization /authorization/organizations/{organization_id}/resources/{resource_type_slug}/{external_id}: get: description: >- Retrieve the details of an authorization resource by its external ID, organization, and resource type. This is useful when you only have the external ID from your system and need to fetch the full resource details. operationId: AuthorizationResourcesByExternalIdController_getByExternalId parameters: - name: organization_id required: true in: path description: The ID of the organization that owns the resource. schema: type: string example: org_01EHZNVPK3SFK441A1RGBFSHRT - name: resource_type_slug required: true in: path description: The slug of the resource type. schema: type: string example: project - name: external_id required: true in: path description: An identifier you provide to reference the resource in your system. schema: type: string 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: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Get a resource by external ID tags: - authorization patch: description: Update an existing authorization resource using its external ID. operationId: AuthorizationResourcesByExternalIdController_updateByExternalId parameters: - name: organization_id required: true in: path description: The ID of the organization that owns the resource. schema: type: string example: org_01EHZNVPK3SFK441A1RGBFSHRT - name: resource_type_slug required: true in: path description: The slug of the resource type. schema: type: string example: project - name: external_id required: true in: path description: An identifier you provide to reference the resource in your system. schema: type: string example: proj-456 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateAuthorizationResourceDto' responses: '200': description: OK 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: Updated Name description: type: - string - 'null' description: An optional description of the Resource. example: Updated description 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: - object - name - description - organization_id - parent_resource_id - id - external_id - 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: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '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: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Update a resource by external ID tags: - authorization x-mutually-exclusive-body-groups: &ref_0 parent_resource: optional: true variants: by_id: - parent_resource_id by_external_id: - parent_resource_external_id - parent_resource_type_slug delete: description: >- Delete an authorization resource by organization, resource type, and external ID. This also deletes all descendant resources. operationId: AuthorizationResourcesByExternalIdController_deleteByExternalId parameters: - name: organization_id required: true in: path description: The ID of the organization that owns the resource. schema: type: string example: org_01EHZNVPK3SFK441A1RGBFSHRT - name: resource_type_slug required: true in: path description: The slug of the resource type. schema: type: string example: project - name: external_id required: true in: path description: An identifier you provide to reference the resource in your system. schema: type: string example: proj-456 - name: cascade_delete required: false in: query description: >- If true, deletes all descendant resources and role assignments. If not set and the resource has children or assignments, the request will fail. schema: type: boolean default: false example: false responses: '204': description: No Content '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: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '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 summary: Delete an authorization resource by external ID tags: - authorization /authorization/organizations/{organization_id}/resources/{resource_type_slug}/{external_id}/organization_memberships: get: description: >- Returns all organization memberships that have a specific permission on a resource, using the resource's external ID. This is useful for answering "Who can access this resource?" when you only have the external ID. operationId: >- AuthorizationResourcesByExternalIdController_listOrganizationMembershipsForResourceByExternalId parameters: - name: organization_id required: true in: path description: The ID of the organization that owns the resource. schema: example: org_01EHZNVPK3SFK441A1RGBFSHRT type: string - name: resource_type_slug required: true in: path description: The slug of the resource type this resource belongs to. schema: example: project type: string - name: external_id required: true in: path description: An identifier you provide to reference the resource in your system. schema: example: proj-456 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: integer - name: order required: false in: query description: >- Order the results by the creation time. Supported values are `"asc"` (ascending), `"desc"` (descending), and `"normal"` (descending with reversed cursor semantics where `before` fetches older records and `after` fetches newer records). schema: $ref: '#/components/schemas/PaginationOrder' - name: permission_slug required: true in: query description: >- The permission slug to filter by. Only users with this permission on the resource are returned. schema: type: string example: project:read - name: assignment required: false in: query description: >- Filter by assignment type. Use "direct" for direct assignments only, or "indirect" to include inherited assignments. schema: type: string enum: - direct - indirect example: direct responses: '200': description: OK content: application/json: schema: $ref: >- #/components/schemas/UserlandUserOrganizationMembershipBaseWithUserList '400': description: Bad Request content: application/json: schema: type: object properties: code: type: string description: The error code identifying the type of error. example: bad_request const: bad_request message: type: string description: A human-readable description of the error. example: Request could not be processed. required: - code - message '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: List memberships for a resource by external ID tags: - authorization /authorization/organizations/{organization_id}/resources/{resource_type_slug}/{external_id}/role_assignments: get: description: >- List all role assignments granted on a resource, identified by its external ID. Each assignment includes the organization membership it was granted to. operationId: >- AuthorizationRoleAssignmentsController_listRoleAssignmentsForResourceByExternalId parameters: - name: organization_id required: true in: path description: The ID of the organization that owns the resource. schema: type: string example: org_01EHZNVPK3SFK441A1RGBFSHRT - name: resource_type_slug required: true in: path description: The slug of the resource type. schema: type: string example: project - name: external_id required: true in: path description: An identifier you provide to reference the resource in your system. schema: type: string example: proj-456 - name: before required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `before="obj_123"` to fetch a new batch of objects before `"obj_123"`. schema: example: xxx_01HXYZ123456789ABCDEFGHIJ type: string - name: after required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `after="obj_123"` to fetch a new batch of objects after `"obj_123"`. schema: example: xxx_01HXYZ987654321KJIHGFEDCBA type: string - name: limit required: false in: query description: >- Upper limit on the number of objects to return, between `1` and `100`. schema: minimum: 1 maximum: 100 default: 10 example: 10 type: integer - name: order required: false in: query description: >- Order the results by the creation time. Supported values are `"asc"` (ascending), `"desc"` (descending), and `"normal"` (descending with reversed cursor semantics where `before` fetches older records and `after` fetches newer records). schema: $ref: '#/components/schemas/PaginationOrder' - name: role_slug required: false in: query description: Filter assignments by the slug of the role. schema: example: editor type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/UserRoleAssignmentList' '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: List role assignments for a resource by external ID tags: - authorization /authorization/permissions: get: description: Get a list of all permissions in your WorkOS environment. operationId: AuthorizationPermissionsController_list parameters: - name: before required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `before="obj_123"` to fetch a new batch of objects before `"obj_123"`. schema: example: xxx_01HXYZ123456789ABCDEFGHIJ type: string - name: after required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `after="obj_123"` to fetch a new batch of objects after `"obj_123"`. schema: example: xxx_01HXYZ987654321KJIHGFEDCBA type: string - name: limit required: false in: query description: >- Upper limit on the number of objects to return, between `1` and `100`. schema: minimum: 1 maximum: 100 default: 10 example: 10 type: integer - name: order required: false in: query description: >- Order the results by the creation time. Supported values are `"asc"` (ascending), `"desc"` (descending), and `"normal"` (descending with reversed cursor semantics where `before` fetches older records and `after` fetches newer records). schema: $ref: '#/components/schemas/PaginationOrder' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AuthorizationPermissionList' '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: List permissions tags: - permissions post: description: >- Create a new permission in your WorkOS environment. The permission can then be assigned to environment roles and custom roles. operationId: AuthorizationPermissionsController_create parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAuthorizationPermissionDto' responses: '201': description: Created content: application/json: schema: type: object properties: object: type: string description: Distinguishes the Permission object. const: permission id: type: string description: Unique identifier of the Permission. example: perm_01HXYZ123456789ABCDEFGHIJ slug: type: string description: >- A unique key to reference the permission. Must be lowercase and contain only letters, numbers, hyphens, underscores, colons, periods, and asterisks. example: documents:read name: type: string description: A descriptive name for the Permission. example: View Documents description: type: - string - 'null' description: An optional description of the Permission. example: Allows viewing document contents system: type: boolean description: >- Whether the permission is a system permission. System permissions are managed by WorkOS and cannot be deleted. example: false resource_type_slug: type: string description: >- The slug of the resource type associated with the permission. example: document created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' updated_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' required: - object - id - slug - name - description - system - resource_type_slug - created_at - updated_at x-inline-with-overrides: true '400': description: Bad Request content: application/json: schema: type: object properties: code: type: string description: The error code identifying the type of error. example: bad_request const: bad_request message: type: string description: A human-readable description of the error. example: Request could not be processed. required: - code - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '409': description: '' content: application/json: schema: type: object properties: code: type: string description: The error code identifying the type of error. example: permission_slug_conflict const: permission_slug_conflict message: type: string description: A human-readable description of the error. example: Request could not be processed. required: - code - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Create a permission tags: - permissions /authorization/permissions/{slug}: get: description: Retrieve a permission by its unique slug. operationId: AuthorizationPermissionsController_find parameters: - name: slug required: true in: path description: >- A unique key to reference the permission. Must be lowercase and contain only letters, numbers, hyphens, underscores, colons, periods, and asterisks. schema: example: documents:read type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AuthorizationPermission' '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Get a permission tags: - permissions patch: description: >- Update an existing permission. Only the fields provided in the request body will be updated. operationId: AuthorizationPermissionsController_update parameters: - name: slug required: true in: path description: >- A unique key to reference the permission. Must be lowercase and contain only letters, numbers, hyphens, underscores, colons, periods, and asterisks. schema: example: documents:read type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateAuthorizationPermissionDto' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AuthorizationPermission' '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Update a permission tags: - permissions delete: description: Delete an existing permission. System permissions cannot be deleted. operationId: AuthorizationPermissionsController_delete parameters: - name: slug required: true in: path description: >- A unique key to reference the permission. Must be lowercase and contain only letters, numbers, hyphens, underscores, colons, periods, and asterisks. schema: example: documents:read type: string responses: '204': description: No Content '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Delete a permission tags: - permissions /authorization/resources: get: description: Get a paginated list of authorization resources. operationId: AuthorizationResourcesController_list parameters: - name: before required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `before="obj_123"` to fetch a new batch of objects before `"obj_123"`. schema: example: xxx_01HXYZ123456789ABCDEFGHIJ type: string - name: after required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `after="obj_123"` to fetch a new batch of objects after `"obj_123"`. schema: example: xxx_01HXYZ987654321KJIHGFEDCBA type: string - name: limit required: false in: query description: >- Upper limit on the number of objects to return, between `1` and `100`. schema: minimum: 1 maximum: 100 default: 10 example: 10 type: integer - name: order required: false in: query description: >- Order the results by the creation time. Supported values are `"asc"` (ascending), `"desc"` (descending), and `"normal"` (descending with reversed cursor semantics where `before` fetches older records and `after` fetches newer records). schema: $ref: '#/components/schemas/PaginationOrder' - name: organization_id required: false in: query description: Filter resources by organization ID. schema: type: string example: org_01EHZNVPK3SFK441A1RGBFSHRT - name: resource_type_slug required: false in: query description: Filter resources by resource type slug. schema: type: string example: project - name: resource_external_id required: false in: query description: Filter resources by external ID. schema: type: string example: my-project-123 - name: parent_resource_id required: false in: query description: >- Filter resources by parent resource ID. Mutually exclusive with `parent_resource_type_slug` and `parent_external_id`. schema: type: string example: authz_resource_01HXYZ123456789ABCDEFGHIJ - name: parent_resource_type_slug required: false in: query description: >- Filter resources by parent resource type slug. Required with `parent_external_id`. Mutually exclusive with `parent_resource_id`. schema: type: string example: workspace - name: parent_external_id required: false in: query description: >- Filter resources by parent external ID. Required with `parent_resource_type_slug`. Mutually exclusive with `parent_resource_id`. schema: type: string example: ext-workspace-123 responses: '200': description: OK 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 summary: List resources tags: - authorization x-mutually-exclusive-parameter-groups: parent: optional: true variants: by_id: - parent_resource_id by_external_id: - parent_resource_type_slug - parent_external_id post: description: Create a new authorization resource. operationId: AuthorizationResourcesController_create parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAuthorizationResourceDto' responses: '201': description: Created 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: Acme Workspace description: type: - string - 'null' description: An optional description of the Resource. example: Primary workspace for the Acme team organization_id: type: string description: The ID of the organization that owns the resource. example: org_01EHQMYV6MBK39QC5PZXHY59C3 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: my-workspace-01 resource_type_slug: type: string description: The slug of the resource type this resource belongs to. 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 - name - description - organization_id - parent_resource_id - id - external_id - resource_type_slug - created_at - updated_at x-inline-with-overrides: true '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: 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: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '409': description: '' content: application/json: schema: 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: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Create an authorization resource tags: - authorization x-mutually-exclusive-body-groups: &ref_6 parent_resource: optional: true variants: by_id: - parent_resource_id by_external_id: - parent_resource_external_id - parent_resource_type_slug /authorization/resources/{resource_id}: get: description: Retrieve the details of an authorization resource by its ID. operationId: AuthorizationResourcesController_findById parameters: - name: resource_id required: true in: path description: The ID of the authorization resource. schema: type: string example: authz_resource_01HXYZ123456789ABCDEFGHIJ responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AuthorizationResource' '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Get a resource tags: - authorization patch: description: Update an existing authorization resource. operationId: AuthorizationResourcesController_update parameters: - name: resource_id required: true in: path description: The ID of the authorization resource. schema: type: string example: authz_resource_01HXYZ123456789ABCDEFGHIJ requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateAuthorizationResourceDto' responses: '200': description: OK 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: Updated Name description: type: - string - 'null' description: An optional description of the Resource. example: Updated description 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: - object - name - description - organization_id - parent_resource_id - id - external_id - 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: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '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: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Update a resource tags: - authorization x-mutually-exclusive-body-groups: *ref_0 delete: description: Delete an authorization resource and all its descendants. operationId: AuthorizationResourcesController_delete parameters: - name: resource_id required: true in: path description: The ID of the authorization resource. schema: type: string example: authz_resource_01HXYZ123456789ABCDEFGHIJ - name: cascade_delete required: false in: query description: >- If true, deletes all descendant resources and role assignments. If not set and the resource has children or assignments, the request will fail. schema: type: boolean default: false example: false responses: '204': description: No Content '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: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '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 summary: Delete an authorization resource tags: - authorization /authorization/resources/{resource_id}/organization_memberships: get: description: >- Returns all organization memberships that have a specific permission on a resource instance. This is useful for answering "Who can access this resource?". operationId: AuthorizationResourcesController_listOrganizationMembershipsForResource parameters: - name: resource_id required: true in: path description: The ID of the authorization resource. schema: type: string example: authz_resource_01HXYZ123456789ABCDEFGHIJ - name: before required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `before="obj_123"` to fetch a new batch of objects before `"obj_123"`. schema: example: xxx_01HXYZ123456789ABCDEFGHIJ type: string - name: after required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `after="obj_123"` to fetch a new batch of objects after `"obj_123"`. schema: example: xxx_01HXYZ987654321KJIHGFEDCBA type: string - name: limit required: false in: query description: >- Upper limit on the number of objects to return, between `1` and `100`. schema: minimum: 1 maximum: 100 default: 10 example: 10 type: integer - name: order required: false in: query description: >- Order the results by the creation time. Supported values are `"asc"` (ascending), `"desc"` (descending), and `"normal"` (descending with reversed cursor semantics where `before` fetches older records and `after` fetches newer records). schema: $ref: '#/components/schemas/PaginationOrder' - name: permission_slug required: true in: query description: >- The permission slug to filter by. Only users with this permission on the resource are returned. schema: type: string example: document:edit - name: assignment required: false in: query description: >- Filter by assignment type. Use `direct` for direct assignments only, or `indirect` to include inherited assignments. schema: type: string enum: - direct - indirect example: direct responses: '200': description: OK content: application/json: schema: $ref: >- #/components/schemas/UserlandUserOrganizationMembershipBaseWithUserList '400': description: Bad Request content: application/json: schema: type: object properties: code: type: string description: The error code identifying the type of error. example: bad_request const: bad_request message: type: string description: A human-readable description of the error. example: Request could not be processed. required: - code - message '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: List organization memberships for resource tags: - authorization /authorization/resources/{resource_id}/role_assignments: get: description: >- List all role assignments granted on a specific resource instance. Each assignment includes the organization membership it was granted to. operationId: AuthorizationRoleAssignmentsController_listRoleAssignmentsForResource parameters: - name: resource_id required: true in: path description: The ID of the authorization resource. schema: type: string example: authz_resource_01HXYZ123456789ABCDEFGHIJ - name: before required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `before="obj_123"` to fetch a new batch of objects before `"obj_123"`. schema: example: xxx_01HXYZ123456789ABCDEFGHIJ type: string - name: after required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `after="obj_123"` to fetch a new batch of objects after `"obj_123"`. schema: example: xxx_01HXYZ987654321KJIHGFEDCBA type: string - name: limit required: false in: query description: >- Upper limit on the number of objects to return, between `1` and `100`. schema: minimum: 1 maximum: 100 default: 10 example: 10 type: integer - name: order required: false in: query description: >- Order the results by the creation time. Supported values are `"asc"` (ascending), `"desc"` (descending), and `"normal"` (descending with reversed cursor semantics where `before` fetches older records and `after` fetches newer records). schema: $ref: '#/components/schemas/PaginationOrder' - name: role_slug required: false in: query description: Filter assignments by the slug of the role. schema: example: editor type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/UserRoleAssignmentList' '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: List role assignments for a resource tags: - authorization /authorization/roles: post: description: Create a new environment role. operationId: AuthorizationRolesController_create parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateRoleDto' responses: '201': description: Created content: application/json: schema: type: object properties: slug: type: string description: A unique slug for the role. example: editor 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: Editor description: type: - string - 'null' description: An optional description of the role. example: Can edit resources type: type: string enum: - EnvironmentRole - OrganizationRole description: >- Whether the role is scoped to the environment or an organization (custom role). example: EnvironmentRole resource_type_slug: type: string description: The slug of the resource type the role is scoped to. example: organization permissions: type: array items: type: string description: The permission slugs assigned to the role. example: - posts:read - posts:write created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' updated_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' required: - slug - object - id - name - description - type - resource_type_slug - permissions - 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 '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '409': description: '' content: application/json: schema: type: object properties: code: type: string description: The error code identifying the type of error. example: role_slug_conflict const: role_slug_conflict message: type: string description: A human-readable description of the error. example: Request could not be processed. required: - code - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Create an environment role tags: - authorization get: description: List all environment roles in priority order. operationId: AuthorizationRolesController_list parameters: [] responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RoleList' '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 summary: List environment roles tags: - authorization /authorization/roles/{slug}: get: description: Get an environment role by its slug. operationId: AuthorizationRolesController_get parameters: - name: slug required: true in: path description: The slug of the environment role. schema: type: string example: admin responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Role' '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Get an environment role tags: - authorization patch: description: Update an existing environment role. operationId: AuthorizationRolesController_update parameters: - name: slug required: true in: path description: The slug of the environment role. schema: type: string example: admin requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateRoleDto' responses: '200': description: OK content: application/json: schema: 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: Super Administrator description: type: - string - 'null' description: An optional description of the role. example: Full administrative access to all resources type: type: string enum: - EnvironmentRole - OrganizationRole description: >- Whether the role is scoped to the environment or an organization (custom role). example: EnvironmentRole resource_type_slug: type: string description: The slug of the resource type the role is scoped to. example: organization permissions: type: array items: type: string description: The permission slugs assigned to the role. example: - posts:read - posts:write created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' updated_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' required: - slug - object - id - name - description - type - resource_type_slug - permissions - 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 '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Update an environment role tags: - authorization /authorization/roles/{slug}/permissions: put: description: Replace all permissions on an environment role with the provided list. operationId: AuthorizationRolePermissionsController_setPermissions parameters: - name: slug required: true in: path description: The slug of the environment role. schema: type: string example: admin requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SetRolePermissionsDto' responses: '200': description: OK content: application/json: schema: 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 (custom role). example: EnvironmentRole resource_type_slug: type: string description: The slug of the resource type the role is scoped to. example: organization permissions: type: array items: type: string description: The permission slugs assigned to the role. example: - billing:read - billing:write - invoices:manage - reports:view 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 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 '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Set permissions for an environment role tags: - authorization post: description: >- Add a single permission to an environment role. If the permission is already assigned to the role, this operation has no effect. operationId: AuthorizationRolePermissionsController_addPermission parameters: - name: slug required: true in: path description: The slug of the environment role. schema: type: string example: admin requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AddRolePermissionDto' responses: '200': description: OK content: application/json: schema: 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 (custom role). example: EnvironmentRole resource_type_slug: type: string description: The slug of the resource type the role is scoped to. example: organization permissions: type: array items: type: string description: The permission slugs assigned to the role. example: - reports:export 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 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 '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Add a permission to an environment role tags: - authorization /connect/applications: get: description: >- List all Connect Applications in the current environment with optional filtering. operationId: ApplicationsController_list parameters: - name: before required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `before="obj_123"` to fetch a new batch of objects before `"obj_123"`. schema: example: xxx_01HXYZ123456789ABCDEFGHIJ type: string - name: after required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `after="obj_123"` to fetch a new batch of objects after `"obj_123"`. schema: example: xxx_01HXYZ987654321KJIHGFEDCBA type: string - name: limit required: false in: query description: >- Upper limit on the number of objects to return, between `1` and `100`. schema: minimum: 1 maximum: 100 default: 10 example: 10 type: integer - name: order required: false in: query description: >- Order the results by the creation time. Supported values are `"asc"` (ascending), `"desc"` (descending), and `"normal"` (descending with reversed cursor semantics where `before` fetches older records and `after` fetches newer records). schema: $ref: '#/components/schemas/PaginationOrder' - name: organization_id required: false in: query description: Filter Connect Applications by organization ID. schema: type: string example: org_01EHZNVPK3SFK441A1RGBFSHRT responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ConnectApplicationList' '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: List Connect Applications tags: - applications post: description: >- Create a new Connect Application. Supports both OAuth and Machine-to-Machine (M2M) application types. operationId: ApplicationsController_create parameters: [] requestBody: required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/CreateOAuthApplicationDto' - $ref: '#/components/schemas/CreateM2MApplicationDto' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/ConnectApplication' '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Create a Connect Application tags: - applications /connect/applications/{id}: get: description: Retrieve details for a specific Connect Application by ID or client ID. operationId: ApplicationsController_find parameters: - name: id required: true in: path description: The application ID or client ID of the Connect Application. schema: type: string example: conn_app_01HXYZ123456789ABCDEFGHIJ responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ConnectApplication' '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Get a Connect Application tags: - applications put: description: >- Update an existing Connect Application. For OAuth applications, you can update redirect URIs. For all applications, you can update the name, description, and scopes. operationId: ApplicationsController_update parameters: - name: id required: true in: path description: The application ID or client ID of the Connect Application. schema: type: string example: conn_app_01HXYZ123456789ABCDEFGHIJ requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateOAuthApplicationDto' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ConnectApplication' '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Update a Connect Application tags: - applications delete: description: Delete an existing Connect Application. operationId: ApplicationsController_delete parameters: - name: id required: true in: path description: The application ID or client ID of the Connect Application. schema: type: string example: conn_app_01HXYZ123456789ABCDEFGHIJ 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 summary: Delete a Connect Application tags: - applications /connect/applications/{id}/client_secrets: get: description: List all client secrets associated with a Connect Application. operationId: ApplicationCredentialsController_list parameters: - name: id required: true in: path description: The application ID or client ID of the Connect Application. schema: type: string example: conn_app_01HXYZ123456789ABCDEFGHIJ responses: '200': description: OK content: application/json: schema: type: array items: 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: format: date-time 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' required: - object - id - secret_hint - last_used_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 summary: List Client Secrets for a Connect Application tags: - application.client-secrets post: description: Create new secrets for a Connect Application. operationId: ApplicationCredentialsController_create parameters: - name: id required: true in: path description: The application ID or client ID of the Connect Application. schema: type: string example: conn_app_01HXYZ123456789ABCDEFGHIJ requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateApplicationSecretDto' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/NewConnectApplicationSecret' '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Create a new client secret for a Connect Application tags: - application.client-secrets /connect/client_secrets/{id}: delete: description: Delete (revoke) an existing client secret. operationId: ApplicationCredentialsController_delete parameters: - name: id required: true in: path description: The unique ID of the client secret. schema: type: string example: secret_01J9Q2Z3X4Y5W6V7U8T9S0R1Q 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 summary: Delete a Client Secret tags: - application.client-secrets /connections: get: description: >- Get a list of all of your existing connections matching the criteria specified. operationId: ConnectionsController_list parameters: - name: before required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. 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: integer - name: order required: false in: query description: Order the results by the creation time. schema: $ref: '#/components/schemas/PaginationOrder' - name: connection_type required: false in: query description: Filter Connections by their type. schema: example: GithubOAuth enum: - ADFSSAML - AdpOidc - AppleOAuth - Auth0SAML - AzureSAML - BitbucketOAuth - CasSAML - CloudflareSAML - ClassLinkSAML - CleverOIDC - 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 - VercelMarketplaceOAuth - VercelOAuth - VMwareSAML - XeroOAuth type: string - name: domain required: false in: query description: Filter Connections by their associated domain. schema: example: foo-corp.com type: string - name: organization_id required: false in: query description: Filter Connections by their associated organization. schema: example: org_01EHWNCE74X7JSDV0X3SZ3KJNY type: string - name: search required: false in: query description: Searchable text to match against Connection names. schema: example: Foo Corp type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ConnectionList' '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 summary: List Connections tags: - connections /connections/{id}: get: description: Get the details of an existing connection. operationId: ConnectionsController_find parameters: - name: id required: true in: path description: Unique identifier for the Connection. schema: example: conn_01E4ZCR3C56J083X43JQXF3JK5 type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Connection' '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Get a Connection tags: - connections delete: description: Permanently deletes an existing connection. It cannot be undone. operationId: ConnectionsController_delete parameters: - name: id required: true in: path description: Unique identifier for the Connection. schema: example: conn_01E4ZCR3C56J083X43JQXF3JK5 type: string responses: '200': description: OK '204': description: No Content '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Delete a Connection tags: - connections /data-integrations/{slug}/authorize: post: description: >- Generates an OAuth authorization URL to initiate the connection flow for a user. Redirect the user to the returned URL to begin the OAuth flow with the third-party provider. operationId: DataIntegrationsController_getDataIntegrationAuthorizeUrl parameters: - name: slug required: true in: path description: >- The slug identifier of the provider (e.g., `github`, `slack`, `notion`). schema: example: github type: string requestBody: required: true content: application/json: schema: type: object properties: user_id: type: string description: The ID of the user to authorize. example: user_01EHZNVPK3SFK441A1RGBFSHRT organization_id: type: string description: >- An organization ID to scope the authorization to a specific organization. example: org_01EHZNVPK3SFK441A1RGBFSHRT return_to: type: string format: uri description: The URL to redirect the user to after authorization. example: https://example.com/callback required: - user_id responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DataIntegrationAuthorizeUrlResponse' '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 '401': description: Unauthorized '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Get authorization URL tags: - pipes /data-integrations/{slug}/token: post: description: >- Fetches a valid OAuth access token for a user's connected account. WorkOS automatically handles token refresh, ensuring you always receive a valid, non-expired token. operationId: DataIntegrationsController_getUserlandUserToken parameters: - name: slug required: true in: path description: The identifier of the integration. schema: example: github type: string requestBody: required: true content: application/json: schema: type: object properties: user_id: type: string description: A [User](/reference/authkit/user) identifier. example: user_01EHZNVPK3SFK441A1RGBFSHRT organization_id: type: string description: >- An [Organization](/reference/organization) identifier. Optional parameter to scope the connection to a specific organization. example: org_01EHZNVPK3SFK441A1RGBFSHRT required: - user_id responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DataIntegrationAccessTokenResponse' '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 '401': description: Unauthorized '404': description: Data integration not found for the given provider slug. content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Get an access token for a connected account tags: - pipes /directories: get: description: >- Get a list of all of your existing directories matching the criteria specified. operationId: DirectoriesController_list parameters: - name: before required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. 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: integer - name: order required: false in: query description: Order the results by the creation time. schema: $ref: '#/components/schemas/PaginationOrder' - name: organization_id required: false in: query description: Filter Directories by their associated organization. schema: example: org_01EHZNVPK3SFK441A1RGBFSHRT type: string - name: search required: false in: query description: Searchable text to match against Directory names. schema: example: Foo Corp type: string - name: domain required: false in: query description: Filter Directories by their associated domain. deprecated: true schema: example: foo-corp.com type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DirectoryList' '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 summary: List Directories tags: - directories /directories/{id}: get: description: Get the details of an existing directory. operationId: DirectoriesController_find parameters: - name: id required: true in: path description: Unique identifier for the Directory. schema: example: directory_01ECAZ4NV9QMV47GW873HDCX74 type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Directory' '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Get a Directory tags: - directories delete: description: Permanently deletes an existing directory. It cannot be undone. operationId: DirectoriesController_deleteDirectory parameters: - name: id required: true in: path description: Unique identifier for the Directory. schema: example: directory_01ECAZ4NV9QMV47GW873HDCX74 type: string responses: '200': description: OK '202': description: '' content: application/json: schema: {} '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 summary: Delete a Directory tags: - directories /directory_groups: get: description: >- Get a list of all of existing directory groups matching the criteria specified. operationId: DirectoryGroupsController_list parameters: - name: before required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `before="obj_123"` to fetch a new batch of objects before `"obj_123"`. schema: example: xxx_01HXYZ123456789ABCDEFGHIJ type: string - name: after required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `after="obj_123"` to fetch a new batch of objects after `"obj_123"`. schema: example: xxx_01HXYZ987654321KJIHGFEDCBA type: string - name: limit required: false in: query description: >- Upper limit on the number of objects to return, between `1` and `100`. schema: minimum: 1 maximum: 100 default: 10 example: 10 type: integer - name: order required: false in: query description: >- Order the results by the creation time. Supported values are `"asc"` (ascending), `"desc"` (descending), and `"normal"` (descending with reversed cursor semantics where `before` fetches older records and `after` fetches newer records). schema: $ref: '#/components/schemas/PaginationOrder' - name: directory required: false in: query description: >- Unique identifier of the WorkOS Directory. This value can be obtained from the WorkOS dashboard or from the WorkOS API. schema: example: directory_01ECAZ4NV9QMV47GW873HDCX74 type: string - name: user required: false in: query description: >- Unique identifier of the WorkOS Directory User. This value can be obtained from the WorkOS API. schema: example: directory_user_01E1JG7J09H96KYP8HM9B0G5SJ type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DirectoryGroupList' '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: List Directory Groups tags: - directory-groups /directory_groups/{id}: get: description: Get the details of an existing Directory Group. operationId: DirectoryGroupsController_find parameters: - name: id required: true in: path description: Unique identifier for the Directory Group. schema: example: directory_group_01E1JJS84MFPPQ3G655FHTKX6Z type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DirectoryGroup' '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Get a Directory Group tags: - directory-groups /directory_users: get: description: >- Get a list of all of existing Directory Users matching the criteria specified. operationId: DirectoryUsersController_list parameters: - name: before required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `before="obj_123"` to fetch a new batch of objects before `"obj_123"`. schema: example: xxx_01HXYZ123456789ABCDEFGHIJ type: string - name: after required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `after="obj_123"` to fetch a new batch of objects after `"obj_123"`. schema: example: xxx_01HXYZ987654321KJIHGFEDCBA type: string - name: limit required: false in: query description: >- Upper limit on the number of objects to return, between `1` and `100`. schema: minimum: 1 maximum: 100 default: 10 example: 10 type: integer - name: order required: false in: query description: >- Order the results by the creation time. Supported values are `"asc"` (ascending), `"desc"` (descending), and `"normal"` (descending with reversed cursor semantics where `before` fetches older records and `after` fetches newer records). schema: $ref: '#/components/schemas/PaginationOrder' - name: directory required: false in: query description: >- Unique identifier of the WorkOS Directory. This value can be obtained from the WorkOS dashboard or from the WorkOS API. schema: example: directory_01ECAZ4NV9QMV47GW873HDCX74 type: string - name: group required: false in: query description: >- Unique identifier of the WorkOS Directory Group. This value can be obtained from the WorkOS API. schema: example: directory_group_01E64QTDNS0EGJ0FMCVY9BWGZT type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DirectoryUserList' '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '429': description: '' content: application/json: schema: type: string const: Ratelimited summary: List Directory Users tags: - directory-users /directory_users/{id}: get: description: Get the details of an existing Directory User. operationId: DirectoryUsersController_find parameters: - name: id required: true in: path description: Unique identifier for the Directory User. schema: example: directory_user_01E1JG7J09H96KYP8HM9B0G5SJ type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DirectoryUserWithGroups' '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Get a Directory User tags: - directory-users /events: get: description: List events for the current environment. operationId: EventsController_list parameters: - name: before required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `before="obj_123"` to fetch a new batch of objects before `"obj_123"`. schema: example: xxx_01HXYZ123456789ABCDEFGHIJ type: string - name: after required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `after="obj_123"` to fetch a new batch of objects after `"obj_123"`. schema: example: xxx_01HXYZ987654321KJIHGFEDCBA type: string - name: limit required: false in: query description: >- Upper limit on the number of objects to return, between `1` and `100`. schema: minimum: 1 maximum: 100 default: 10 example: 10 type: integer - name: order required: false in: query description: >- Order the results by the creation time. Supported values are `"asc"` (ascending), `"desc"` (descending), and `"normal"` (descending with reversed cursor semantics where `before` fetches older records and `after` fetches newer records). schema: $ref: '#/components/schemas/PaginationOrder' - name: events required: false in: query description: >- Filter events by one or more event types (e.g. `dsync.user.created`). style: form explode: false schema: example: - dsync.user.created - dsync.user.updated type: array items: type: string - name: range_start required: false in: query description: ISO-8601 date string to filter events created after this date. schema: example: '2025-01-01T00:00:00Z' type: string - name: range_end required: false in: query description: ISO-8601 date string to filter events created before this date. schema: example: '2025-12-31T23:59:59Z' type: string - name: organization_id required: false in: query description: >- Filter events by the [Organization](/reference/organization) that the event is associated with. schema: example: org_01EHQMYV6MBK39QC5PZXHY59C3 type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/EventList' '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 '422': description: Unprocessable Entity content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string description: The validation error code. example: required field: type: string description: The field that failed validation. example: events required: - code - field description: The list of validation errors. message: type: string description: A human-readable description of the error. example: Validation failed. required: - errors - message summary: List events tags: - events /feature-flags: get: description: >- Get a list of all of your existing feature flags matching the criteria specified. operationId: FeatureFlagsController_list parameters: - name: before required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. 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: integer - name: order required: false in: query description: Order the results by the creation time. schema: $ref: '#/components/schemas/PaginationOrder' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/FlagList' '400': description: Bad Request 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 '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: List feature flags tags: - feature-flags /feature-flags/{slug}: get: description: Get the details of an existing feature flag by its slug. operationId: FeatureFlagsController_findBySlug parameters: - name: slug required: true in: path description: A unique key to reference the Feature Flag. schema: type: string example: advanced-analytics responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Flag' '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Get a feature flag tags: - feature-flags /feature-flags/{slug}/disable: put: description: Disables a feature flag in the current environment. operationId: FeatureFlagsController_disableFlag parameters: - name: slug required: true in: path description: A unique key to reference the Feature Flag. schema: type: string example: advanced-analytics responses: '200': description: OK 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: false 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 x-inline-with-overrides: true '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Disable a feature flag tags: - feature-flags /feature-flags/{slug}/enable: put: description: Enables a feature flag in the current environment. operationId: FeatureFlagsController_enableFlag parameters: - name: slug required: true in: path description: A unique key to reference the Feature Flag. schema: type: string example: advanced-analytics responses: '200': description: OK 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 x-inline-with-overrides: true '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Enable a feature flag tags: - feature-flags /feature-flags/{slug}/targets/{resourceId}: post: description: >- Enables a feature flag for a specific target in the current environment. Currently, supported targets include users and organizations. operationId: FlagTargetsController_createTarget parameters: - name: resourceId required: true in: path description: The resource ID in format "user_" or "org_". schema: example: user_01234567890abcdef type: string - name: slug required: true in: path description: The unique slug identifier of the feature flag. schema: example: beta-feature type: string responses: '204': description: Target created or updated successfully. '400': description: Invalid resourceId format. content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: Invalid resource id code: type: string description: The error code identifying the type of error. example: invalid_resource_id_format statusCode: type: number description: The HTTP status code. example: 400 '403': description: Access denied. 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: Feature flag, user, or organization not found. content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Add a feature flag target tags: - feature-flags.targets delete: description: >- Removes a target from the feature flag's target list in the current environment. Currently, supported targets include users and organizations. operationId: FlagTargetsController_deleteTarget parameters: - name: resourceId required: true in: path description: The resource ID in format "user_" or "org_". schema: example: user_01234567890abcdef type: string - name: slug required: true in: path description: The unique slug identifier of the feature flag. schema: example: beta-feature type: string responses: '204': description: Target deleted successfully. '400': description: Invalid resourceId format. content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: Invalid resource id code: type: string description: The error code identifying the type of error. example: invalid_resource_id_format statusCode: type: number description: The HTTP status code. example: 400 '403': description: Access denied. 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: Feature flag, user, or organization not found. content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Remove a feature flag target tags: - feature-flags.targets /organization_domains: post: description: Creates a new Organization Domain. operationId: OrganizationDomainsController_create parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateOrganizationDomainDto' responses: '201': description: Created 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_01EHQMYV6MBK39QC5PZXHY59C3 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 x-inline-with-overrides: true '409': description: '' content: application/json: schema: type: object properties: code: type: string description: The error code identifying the type of error. const: domain_already_exists message: type: string description: A human-readable description of the error. example: Domain already exists for this organization. required: - code - message summary: Create an Organization Domain tags: - organization-domains /organization_domains/{id}: get: description: Get the details of an existing organization domain. operationId: OrganizationDomainsController_get parameters: - name: id required: true in: path description: Unique identifier of the organization domain. schema: type: string example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/OrganizationDomainStandAlone' '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Get an Organization Domain tags: - organization-domains delete: description: Permanently deletes an organization domain. It cannot be undone. operationId: OrganizationDomainsController_delete parameters: - name: id required: true in: path description: Unique identifier of the organization domain. schema: type: string example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A responses: '204': description: Organization domain deleted successfully. '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Delete an Organization Domain tags: - organization-domains /organization_domains/{id}/verify: post: description: Initiates verification process for an Organization Domain. operationId: OrganizationDomainsController_verify parameters: - name: id required: true in: path description: Unique identifier of the organization domain. schema: type: string example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/OrganizationDomainStandAlone' '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: type: string description: A human-readable description of the error. example: Domain is already verified. required: - code - message summary: Verify an Organization Domain tags: - organization-domains /organizations: get: description: >- Get a list of all of your existing organizations matching the criteria specified. operationId: OrganizationsController_list parameters: - name: before required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `before="obj_123"` to fetch a new batch of objects before `"obj_123"`. schema: example: xxx_01HXYZ123456789ABCDEFGHIJ type: string - name: after required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `after="obj_123"` to fetch a new batch of objects after `"obj_123"`. schema: example: xxx_01HXYZ987654321KJIHGFEDCBA type: string - name: limit required: false in: query description: >- Upper limit on the number of objects to return, between `1` and `100`. schema: minimum: 1 maximum: 100 default: 10 example: 10 type: integer - name: order required: false in: query description: >- Order the results by the creation time. Supported values are `"asc"` (ascending), `"desc"` (descending), and `"normal"` (descending with reversed cursor semantics where `before` fetches older records and `after` fetches newer records). schema: $ref: '#/components/schemas/PaginationOrder' - name: domains required: false in: query description: >- The domains of an Organization. Any Organization with a matching domain will be returned. style: form explode: false schema: type: array items: type: string example: - foo-corp.com - name: search required: false in: query description: >- Searchable text for an Organization. Matches against the organization name. schema: type: string example: Acme Corp responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/OrganizationList' '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: List Organizations tags: - organizations post: description: Creates a new organization in the current environment. operationId: OrganizationsController_create parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/OrganizationDto' responses: '201': content: application/json: schema: $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: application/json: schema: oneOf: - 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 '409': description: '' content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Create an Organization tags: - organizations /organizations/external_id/{external_id}: get: description: >- Get the details of an existing organization by an [external identifier](/authkit/metadata/external-identifiers). operationId: OrganizationsController_getByExternalId parameters: - name: external_id required: true in: path description: The external ID of the Organization. schema: type: string example: 2fe01467-f7ea-4dd2-8b79-c2b4f56d0191 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Organization' '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Get an Organization by External ID tags: - organizations /organizations/{id}: get: description: Get the details of an existing organization. operationId: OrganizationsController_find parameters: - name: id required: true in: path description: Unique identifier of the Organization. schema: type: string example: org_01EHZNVPK3SFK441A1RGBFSHRT responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Organization' '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Get an Organization tags: - organizations put: description: Updates an organization in the current environment. operationId: OrganizationsController_updateOrganization parameters: - name: id 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/UpdateOrganizationDto' responses: '200': content: application/json: schema: $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: application/json: schema: oneOf: - 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: stripe_customer_id_already_used const: stripe_customer_id_already_used message: type: string description: A human-readable description of the error. example: Request could not be processed. required: - code - message '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '409': description: '' content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Update an Organization tags: - organizations delete: description: >- Permanently deletes an organization in the current environment. It cannot be undone. operationId: OrganizationsController_deleteOrganization parameters: - name: id required: true in: path description: Unique identifier of the Organization. schema: type: string example: org_01EHZNVPK3SFK441A1RGBFSHRT responses: '200': description: OK '202': description: '' '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 summary: Delete an Organization tags: - organizations /organizations/{id}/audit_log_configuration: get: description: >- Get the unified view of audit log trail and stream configuration for an organization. operationId: OrganizationsController_getAuditLogConfiguration parameters: - name: id required: true in: path description: Unique identifier of the Organization. schema: type: string example: org_01EHZNVPK3SFK441A1RGBFSHRT responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AuditLogConfiguration' '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Get Audit Log Configuration tags: - organizations /organizations/{id}/audit_logs_retention: get: description: Get the configured event retention period for the given Organization. operationId: AuditLogsRetentionController_auditLogsRetention parameters: - name: id required: true in: path description: Unique identifier of the Organization. schema: type: string example: org_01EHZNVPK3SFK441A1RGBFSHRT responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AuditLogsRetentionJson' '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Get Retention tags: - audit-logs put: description: Set the event retention period for the given Organization. operationId: AuditLogsRetentionController_updateAuditLogsRetention parameters: - name: id 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/UpdateAuditLogsRetentionDto' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AuditLogsRetentionJson' '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Set Retention tags: - audit-logs /organizations/{organizationId}/api_keys: get: description: Get a list of all API keys for an organization. operationId: OrganizationApiKeysController_list parameters: - name: organizationId required: true in: path description: Unique identifier of the Organization. schema: type: string example: org_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. 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: integer - name: order required: false in: query description: Order the results by the creation time. schema: $ref: '#/components/schemas/PaginationOrder' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/OrganizationApiKeyList' '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: List API keys for an organization tags: - organizations.api_keys post: description: Create a new API key for an organization. operationId: OrganizationApiKeysController_create 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/OrganizationApiKeyWithValue' '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 properties: code: type: string description: The validation error code. example: required field: type: string description: The field that failed validation. example: event.action required: - code - field description: The list of validation errors. required: - message - errors summary: Create an API key for an organization tags: - organizations.api_keys /organizations/{organizationId}/feature-flags: get: description: Get a list of all enabled feature flags for an organization. operationId: OrganizationFeatureFlagsController_list parameters: - name: organizationId required: true in: path description: Unique identifier of the Organization. schema: type: string example: org_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. 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: integer - name: order required: false in: query description: Order the results by the creation time. schema: $ref: '#/components/schemas/PaginationOrder' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/FlagList' '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: List enabled feature flags for an organization tags: - organizations.feature-flags /organizations/{organizationId}/groups: post: description: Create a new group within an organization. operationId: GroupsController_create parameters: - name: organizationId required: true in: path description: The ID of the organization. schema: type: string example: org_01EHWNCE74X7JSDV0X3SZ3KJNY requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateGroupDto' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/Group' '400': description: Bad Request content: application/json: schema: type: object properties: code: type: string description: The error code identifying the type of error. example: bad_request const: bad_request message: type: string description: A human-readable description of the error. example: Request could not be processed. required: - code - message '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Create a group tags: - groups x-feature-flag: user-groups-enabled get: description: Get a paginated list of groups within an organization. operationId: GroupsController_list parameters: - name: organizationId required: true in: path description: The ID of the organization. schema: type: string example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - name: before required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `before="obj_123"` to fetch a new batch of objects before `"obj_123"`. schema: example: xxx_01HXYZ123456789ABCDEFGHIJ type: string - name: after required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `after="obj_123"` to fetch a new batch of objects after `"obj_123"`. schema: example: xxx_01HXYZ987654321KJIHGFEDCBA type: string - name: limit required: false in: query description: >- Upper limit on the number of objects to return, between `1` and `100`. schema: minimum: 1 maximum: 100 default: 10 example: 10 type: integer - name: order required: false in: query description: >- Order the results by the creation time. Supported values are `"asc"` (ascending), `"desc"` (descending), and `"normal"` (descending with reversed cursor semantics where `before` fetches older records and `after` fetches newer records). schema: $ref: '#/components/schemas/PaginationOrder' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/GroupList' '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: List groups tags: - groups x-feature-flag: user-groups-enabled /organizations/{organizationId}/groups/{groupId}: get: description: Retrieve a group by its ID within an organization. operationId: GroupsController_get parameters: - name: organizationId required: true in: path description: The ID of the organization. schema: type: string example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - name: groupId required: true in: path description: The ID of the group. schema: type: string example: group_01HXYZ123456789ABCDEFGHIJ responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Group' '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Get a group tags: - groups x-feature-flag: user-groups-enabled patch: description: >- Update an existing group. Only the fields provided in the request body will be updated. operationId: GroupsController_update parameters: - name: organizationId required: true in: path description: The ID of the organization. schema: type: string example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - name: groupId required: true in: path description: The ID of the group. schema: type: string example: group_01HXYZ123456789ABCDEFGHIJ requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateGroupDto' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Group' '400': description: Bad Request content: application/json: schema: type: object properties: code: type: string description: The error code identifying the type of error. example: bad_request const: bad_request message: type: string description: A human-readable description of the error. example: Request could not be processed. required: - code - message '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Update a group tags: - groups x-feature-flag: user-groups-enabled delete: description: Delete a group from an organization. operationId: GroupsController_delete parameters: - name: organizationId required: true in: path description: The ID of the organization. schema: type: string example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - name: groupId required: true in: path description: The ID of the group. schema: type: string example: group_01HXYZ123456789ABCDEFGHIJ responses: '204': description: No Content '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Delete a group tags: - groups x-feature-flag: user-groups-enabled /organizations/{organizationId}/groups/{groupId}/organization-memberships: post: description: Add an organization membership to a group. operationId: GroupMembershipsController_addMember parameters: - name: organizationId required: true in: path description: Unique identifier of the Organization. schema: type: string example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - name: groupId required: true in: path description: Unique identifier of the Group. schema: type: string example: group_01HXYZ123456789ABCDEFGHIJ requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateGroupMembershipDto' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Group' '400': description: Bad Request content: application/json: schema: type: object properties: code: type: string description: The error code identifying the type of error. example: group_membership_limit_exceeded const: group_membership_limit_exceeded message: type: string description: A human-readable description of the error. example: Request could not be processed. required: - code - message '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Add a member to a Group tags: - groups x-feature-flag: user-groups-enabled get: description: Get a list of organization memberships in a group. operationId: GroupMembershipsController_listMembers parameters: - name: organizationId required: true in: path description: Unique identifier of the Organization. schema: type: string example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - name: groupId required: true in: path description: Unique identifier of the Group. schema: type: string example: group_01HXYZ123456789ABCDEFGHIJ - name: before required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `before="obj_123"` to fetch a new batch of objects before `"obj_123"`. schema: example: xxx_01HXYZ123456789ABCDEFGHIJ type: string - name: after required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `after="obj_123"` to fetch a new batch of objects after `"obj_123"`. schema: example: xxx_01HXYZ987654321KJIHGFEDCBA type: string - name: limit required: false in: query description: >- Upper limit on the number of objects to return, between `1` and `100`. schema: minimum: 1 maximum: 100 default: 10 example: 10 type: integer - name: order required: false in: query description: >- Order the results by the creation time. Supported values are `"asc"` (ascending), `"desc"` (descending), and `"normal"` (descending with reversed cursor semantics where `before` fetches older records and `after` fetches newer records). schema: $ref: '#/components/schemas/PaginationOrder' responses: '200': description: OK content: application/json: schema: $ref: >- #/components/schemas/UserlandUserOrganizationMembershipBaseList '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: List Group members tags: - groups x-feature-flag: user-groups-enabled /organizations/{organizationId}/groups/{groupId}/organization-memberships/{omId}: delete: description: Remove an organization membership from a group. operationId: GroupMembershipsController_removeMember parameters: - name: organizationId required: true in: path description: Unique identifier of the Organization. schema: type: string example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - name: groupId required: true in: path description: Unique identifier of the Group. schema: type: string example: group_01HXYZ123456789ABCDEFGHIJ - name: omId required: true in: path description: Unique identifier of the Organization Membership. schema: type: string example: om_01HXYZ123456789ABCDEFGHIJ responses: '204': description: No Content '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Remove a member from a Group tags: - groups x-feature-flag: user-groups-enabled /portal/generate_link: post: description: Generate a Portal Link scoped to an Organization. operationId: PortalSessionsController_create parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GenerateLinkDto' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/PortalLinkResponse' '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 '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Generate a Portal Link tags: - admin-portal /radar/attempts: post: description: Assess a request for risk using the Radar engine and receive a verdict. operationId: RadarStandaloneController_assess parameters: [] requestBody: required: true content: application/json: schema: type: object properties: ip_address: type: string description: The IP address of the request to assess. example: 49.78.240.97 user_agent: type: string description: The user agent string of the request to assess. example: Mozilla/5.0 email: type: string format: email description: The email address of the user making the request. example: user@example.com auth_method: type: string enum: - Password - Passkey - Authenticator - SMS_OTP - Email_OTP - Social - SSO - Other description: The authentication method being used. example: Password action: description: The action being performed. example: sign-in type: string enum: - sign-up - sign-in required: - ip_address - user_agent - email - auth_method - action responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RadarStandaloneResponse' '400': description: Standalone radar is not enabled. content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Create an attempt tags: - radar /radar/attempts/{id}: put: description: >- You may optionally inform Radar that an authentication attempt or challenge was successful using this endpoint. Some Radar controls depend on tracking recent successful attempts, such as impossible travel. operationId: RadarStandaloneController_updateRadarAttempt parameters: - name: id required: true in: path description: The unique identifier of the Radar attempt to update. schema: example: radar_att_01HZBC6N1EB1ZY7KG32X type: string requestBody: required: true content: application/json: schema: type: object properties: challenge_status: type: string description: Set to `"success"` to mark the challenge as completed. example: success const: success attempt_status: type: string description: >- Set to `"success"` to mark the authentication attempt as successful. example: success const: success responses: '204': description: Radar attempt updated. '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 '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Update a Radar attempt tags: - radar /radar/lists/{type}/{action}: post: description: Add an entry to a Radar list. operationId: RadarStandaloneController_updateRadarList parameters: - name: type required: true in: path description: The type of the Radar list (e.g. ip_address, domain, email). schema: type: string enum: - ip_address - domain - email - device - user_agent - device_fingerprint - country example: ip_address - name: action required: true in: path description: >- The list action indicating whether to add the entry to the allow or block list. schema: type: string enum: - block - allow example: block requestBody: required: true content: application/json: schema: type: object properties: entry: type: string description: >- The value to add to the list. Must match the format of the list type (e.g. a valid IP address for `ip_address`, a valid email for `email`). example: 198.51.100.42 required: - entry responses: '200': description: Entry already present in the list. content: application/json: schema: $ref: '#/components/schemas/RadarListEntryAlreadyPresentResponse' '201': description: Created '204': description: Entry successfully added to the list. '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 summary: Add an entry to a Radar list tags: - radar delete: description: Remove an entry from a Radar list. operationId: RadarStandaloneController_deleteRadarListEntry parameters: - name: type required: true in: path description: The type of the Radar list (e.g. ip_address, domain, email). schema: type: string enum: - ip_address - domain - email - device - user_agent - device_fingerprint - country example: ip_address - name: action required: true in: path description: >- The list action indicating whether to remove the entry from the allow or block list. schema: type: string enum: - block - allow example: block requestBody: required: true content: application/json: schema: type: object properties: entry: type: string description: >- The value to remove from the list. Must match an existing entry. example: 198.51.100.42 required: - entry responses: '204': description: Radar list updated. '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 '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Remove an entry from a Radar list tags: - radar /sso/authorize: get: description: Initiates the single sign-on flow. operationId: SsoController_authorize parameters: - name: provider_scopes required: false in: query description: >- Additional scopes to request from the identity provider. Applicable when using OAuth or OpenID Connect connections. style: form explode: false schema: type: array items: type: string example: - openid - profile - email - name: provider_query_params required: false in: query description: >- Key/value pairs of query parameters to pass to the OAuth provider. Only applicable when using OAuth connections. schema: additionalProperties: type: string example: hd: example.com access_type: offline type: object - name: client_id required: true in: query schema: type: string example: client_01HZBC6N1EB1ZY7KG32X description: The unique identifier of the WorkOS environment client. - name: domain required: false in: query deprecated: true schema: type: string example: example.com description: >- Deprecated. Use `connection` or `organization` instead. Used to initiate SSO for a connection by domain. The domain must be associated with a connection in your WorkOS environment. - name: provider required: false in: query schema: type: string enum: - AppleOAuth - BitbucketOAuth - GitHubOAuth - GitLabOAuth - GoogleOAuth - IntuitOAuth - LinkedInOAuth - MicrosoftOAuth - SalesforceOAuth - SlackOAuth - VercelMarketplaceOAuth - VercelOAuth - XeroOAuth example: GoogleOAuth description: Used to initiate OAuth authentication with various providers. - name: redirect_uri required: true in: query schema: type: string format: uri example: https://example.com/callback description: >- Where to redirect the user after they complete the authentication process. You must use one of the redirect URIs configured via the [Redirects](https://dashboard.workos.com/redirects) page on the dashboard. - name: response_type required: true in: query schema: type: string example: code const: code description: >- The only valid option for the response type parameter is `"code"`. The `"code"` parameter value initiates an [authorization code grant type](https://tools.ietf.org/html/rfc6749#section-4.1). This grant type allows you to exchange an authorization code for an access token during the redirect that takes place after a user has authenticated with an identity provider. - name: state required: false in: query schema: type: string example: dj1kUXc0dzlXZ1hjUQ== description: >- An optional parameter that can be used to encode arbitrary information to help restore application state between redirects. If included, the redirect URI received from WorkOS will contain the exact `state` that was passed. - name: connection required: false in: query schema: type: string example: conn_01E4ZCR3C56J083X43JQXF3JK5 description: >- Used to initiate SSO for a connection. The value should be a WorkOS connection ID. You can persist the WorkOS connection ID with application user or team identifiers. WorkOS will use the connection indicated by the connection parameter to direct the user to the corresponding IdP for authentication. - name: organization required: false in: query schema: type: string example: org_01EHQMYV6MBK39QC5PZXHY59C3 description: >- Used to initiate SSO for an organization. The value should be a WorkOS organization ID. You can persist the WorkOS organization ID with application user or team identifiers. WorkOS will use the organization ID to determine the appropriate connection and the IdP to direct the user to for authentication. - name: domain_hint required: false in: query schema: type: string example: example.com description: >- Can be used to pre-fill the domain field when initiating authentication with Microsoft OAuth or with a Google SAML connection type. - name: login_hint required: false in: query schema: type: string example: user@example.com description: >- Can be used to pre-fill the username/email address field of the IdP sign-in page for the user, if you know their username ahead of time. Currently supported for OAuth, OpenID Connect, Okta, Entra ID, and custom SAML connections. - name: nonce required: false in: query schema: type: string example: abc123def456 description: >- A random string generated by the client that is used to mitigate replay attacks. responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SsoAuthorizeUrlResponse' '302': headers: Location: schema: type: string format: uri description: '' security: [] summary: Initiate SSO tags: - sso /sso/jwks/{clientId}: get: description: >- Returns the JSON Web Key Set (JWKS) containing the public keys used for verifying access tokens. operationId: SsoController_jsonWebKeySet parameters: - name: clientId required: true in: path description: >- Identifies the application making the request to the WorkOS server. You can obtain your client ID from the [API Keys](https://dashboard.workos.com/api-keys) page in the dashboard. schema: type: string example: client_01HXYZ123456789ABCDEFGHIJ responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/JwksResponse' '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 security: [] summary: Get JWKS tags: - user-management.session-tokens /sso/logout: get: description: >- Logout allows to sign out a user from your application by triggering the identity provider sign out flow. This `GET` endpoint should be a redirection, since the identity provider user will be identified in the browser session. Before redirecting to this endpoint, you need to generate a short-lived logout token using the [Logout Authorize](/reference/sso/logout/authorize) endpoint. operationId: SsoController_logout parameters: - name: token required: true in: query description: >- The logout token returned from the [Logout Authorize](/reference/sso/logout/authorize) endpoint. schema: type: string example: >- eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwcm9maWxlX2lkIjoicHJvZl8wMUdXUTFHMEgyRk02QVNFRjBIUzEzSENXOS0zMDRrZzAzZyIsImV4cCI6IjE1MTYyMzkwMjIifQ.Wru9Qlnf5DpohtGCKhZU4cVOd3zpiu7QQ-XEX--5A_4 responses: '200': description: OK '302': headers: Location: schema: type: string format: uri description: '' '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 security: [] servers: - url: https://auth.workos.com summary: Logout Redirect tags: - sso /sso/logout/authorize: post: description: >- You should call this endpoint from your server to generate a logout token which is required for the [Logout Redirect](/reference/sso/logout) endpoint. operationId: SsoController_logoutAuthorize parameters: [] requestBody: required: true content: application/json: schema: type: object properties: profile_id: type: string description: The unique ID of the profile to log out. example: prof_01HXYZ123456789ABCDEFGHIJ required: - profile_id responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SsoLogoutAuthorizeResponse' '201': description: Created '400': description: Bad Request content: application/json: schema: oneOf: - type: object properties: error: type: string const: connection_invalid error_description: type: string description: A human-readable description of the error. example: >- Single Logout is only supported for GenericOIDC connections. required: - error - error_description - type: object properties: error: type: string const: unauthorized_client error_description: type: string description: A human-readable description of the error. example: Unauthorized required: - error - error_description '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 servers: - url: https://auth.workos.com summary: Logout Authorize tags: - sso /sso/profile: get: description: >- Exchange an access token for a user's [Profile](/reference/sso/profile). Because this profile is returned in the [Get a Profile and Token endpoint](/reference/sso/profile/get-profile-and-token) your application usually does not need to call this endpoint. It is available for any authentication flows that require an additional endpoint to retrieve a user's profile. operationId: SsoController_getProfile parameters: [] responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Profile' '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: string const: Unauthorized required: - 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 security: - access_token: [] summary: Get a User Profile tags: - sso /sso/token: post: description: >- Get an access token along with the user [Profile](/reference/sso/profile) using the code passed to your [Redirect URI](/reference/sso/get-authorization-url/redirect-uri). operationId: SsoController_token parameters: - name: client_id required: true in: query description: The client ID of the WorkOS environment. schema: example: client_01HZBC6N1EB1ZY7KG32X type: string - name: client_secret required: true in: query description: The client secret of the WorkOS environment. schema: example: sk_example_123456789 type: string - name: code required: true in: query description: The authorization code received from the authorization callback. schema: example: authorization_code_value type: string - name: grant_type required: true in: query description: The grant type for the token request. schema: example: authorization_code type: string const: authorization_code requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TokenQueryDto' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SsoTokenResponse' '201': description: Created '400': description: Bad Request content: application/json: schema: oneOf: - type: object properties: error: type: string const: invalid_client error_description: type: string description: A human-readable description of the error. example: Invalid client ID or secret. required: - error - error_description - type: object properties: error: type: string const: unauthorized_client error_description: type: string description: A human-readable description of the error. example: The client is not authorized to use this grant type. required: - error - error_description - type: object properties: error: type: string const: invalid_grant error_description: type: string description: A human-readable description of the error. example: The code has expired or has already been used. required: - error - error_description - type: object properties: error: type: string const: unsupported_grant_type error_description: type: string description: A human-readable description of the error. example: The grant type is not supported. required: - error - error_description '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 security: [] summary: Get a Profile and Token tags: - sso /user_management/authenticate: post: description: >- Authenticate a user with a specified [authentication method](/reference/authkit/authentication). operationId: UserlandSessionsController_authenticate[0] parameters: [] requestBody: required: true content: application/json: schema: oneOf: - type: object properties: client_id: type: string description: The client ID of the application. example: client_01HXYZ123456789ABCDEFGHIJ client_secret: type: string description: The client secret of the application. example: sk_test_.... grant_type: type: string const: authorization_code code: type: string description: The authorization code received from the redirect. example: vBqZKaPpsnJlPfXiDqN7b6VTz code_verifier: type: string description: >- The PKCE code verifier used to derive the code challenge passed to the authorization URL. example: dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk invitation_token: type: string description: An invitation token to accept during authentication. example: inv_tok_01HXYZ123456789ABCDEFGHIJ ip_address: type: string description: The IP address of the user's request. example: 203.0.113.42 device_id: type: string description: A unique identifier for the device. example: device_01HXYZ123456789ABCDEFGHIJ user_agent: type: string description: The user agent string from the user's browser. example: Mozilla/5.0 required: - client_id - client_secret - grant_type - code - type: object properties: client_id: type: string description: The client ID of the application. example: client_01HXYZ123456789ABCDEFGHIJ client_secret: type: string description: The client secret of the application. example: sk_test_.... grant_type: type: string const: password email: type: string description: The user's email address. example: user@example.com password: type: string description: The user's password. example: strong_password_123! invitation_token: type: string description: An invitation token to accept during authentication. example: inv_tok_01HXYZ123456789ABCDEFGHIJ ip_address: type: string description: The IP address of the user's request. example: 203.0.113.42 device_id: type: string description: A unique identifier for the device. example: device_01HXYZ123456789ABCDEFGHIJ user_agent: type: string description: The user agent string from the user's browser. example: Mozilla/5.0 required: - client_id - client_secret - grant_type - email - password - type: object properties: client_id: type: string description: The client ID of the application. example: client_01HXYZ123456789ABCDEFGHIJ client_secret: type: string description: The client secret of the application. example: sk_test_.... grant_type: type: string const: refresh_token refresh_token: type: string description: The refresh token to exchange for new tokens. example: yAjhKk23hJMM3DaR... organization_id: type: string description: The ID of the organization to scope the session to. example: org_01EHQMYV6MBK39QC5PZXHY59C3 ip_address: type: string description: The IP address of the user's request. example: 203.0.113.42 device_id: type: string description: A unique identifier for the device. example: device_01HXYZ123456789ABCDEFGHIJ user_agent: type: string description: The user agent string from the user's browser. example: Mozilla/5.0 required: - client_id - client_secret - grant_type - refresh_token - type: object properties: client_id: type: string description: The client ID of the application. example: client_01HXYZ123456789ABCDEFGHIJ client_secret: type: string description: The client secret of the application. example: sk_test_.... grant_type: type: string const: urn:workos:oauth:grant-type:magic-auth:code code: type: string description: The one-time code for Magic Auth authentication. example: '123456' email: type: string description: The user's email address. example: user@example.com invitation_token: type: string description: An invitation token to accept during authentication. example: inv_tok_01HXYZ123456789ABCDEFGHIJ ip_address: type: string description: The IP address of the user's request. example: 203.0.113.42 device_id: type: string description: A unique identifier for the device. example: device_01HXYZ123456789ABCDEFGHIJ user_agent: type: string description: The user agent string from the user's browser. example: Mozilla/5.0 required: - client_id - client_secret - grant_type - code - email - type: object properties: client_id: type: string description: The client ID of the application. example: client_01HXYZ123456789ABCDEFGHIJ client_secret: type: string description: The client secret of the application. example: sk_test_.... grant_type: type: string const: urn:workos:oauth:grant-type:email-verification:code code: type: string description: The email verification code. example: '123456' pending_authentication_token: type: string description: >- The pending authentication token from a previous authentication attempt. example: cTDQJTTkTkkVYxbn... ip_address: type: string description: The IP address of the user's request. example: 203.0.113.42 device_id: type: string description: A unique identifier for the device. example: device_01HXYZ123456789ABCDEFGHIJ user_agent: type: string description: The user agent string from the user's browser. example: Mozilla/5.0 required: - client_id - client_secret - grant_type - code - pending_authentication_token - type: object properties: client_id: type: string description: The client ID of the application. example: client_01HXYZ123456789ABCDEFGHIJ client_secret: type: string description: The client secret of the application. example: sk_test_.... grant_type: type: string const: urn:workos:oauth:grant-type:mfa-totp code: type: string description: The TOTP code from the authenticator app. example: '123456' pending_authentication_token: type: string description: >- The pending authentication token from a previous authentication attempt. example: cTDQJTTkTkkVYxbn... authentication_challenge_id: type: string description: The ID of the MFA authentication challenge. example: auth_challenge_01HXYZ123456789ABCDEFGHIJ ip_address: type: string description: The IP address of the user's request. example: 203.0.113.42 device_id: type: string description: A unique identifier for the device. example: device_01HXYZ123456789ABCDEFGHIJ user_agent: type: string description: The user agent string from the user's browser. example: Mozilla/5.0 required: - client_id - client_secret - grant_type - code - pending_authentication_token - authentication_challenge_id - type: object properties: client_id: type: string description: The client ID of the application. example: client_01HXYZ123456789ABCDEFGHIJ client_secret: type: string description: The client secret of the application. example: sk_test_.... grant_type: type: string const: urn:workos:oauth:grant-type:organization-selection pending_authentication_token: type: string description: >- The pending authentication token from a previous authentication attempt. example: cTDQJTTkTkkVYxbn... organization_id: type: string description: The ID of the organization the user selected. example: org_01EHQMYV6MBK39QC5PZXHY59C3 ip_address: type: string description: The IP address of the user's request. example: 203.0.113.42 device_id: type: string description: A unique identifier for the device. example: device_01HXYZ123456789ABCDEFGHIJ user_agent: type: string description: The user agent string from the user's browser. example: Mozilla/5.0 required: - client_id - client_secret - grant_type - pending_authentication_token - organization_id - type: object properties: client_id: type: string description: The client ID of the application. example: client_01HXYZ123456789ABCDEFGHIJ grant_type: type: string const: urn:ietf:params:oauth:grant-type:device_code device_code: type: string description: The device verification code. example: Ao4fMrDS... ip_address: type: string description: The IP address of the user's request. example: 203.0.113.42 device_id: type: string description: A unique identifier for the device. example: device_01HXYZ123456789ABCDEFGHIJ user_agent: type: string description: The user agent string from the user's browser. example: Mozilla/5.0 required: - client_id - grant_type - device_code responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/UserlandAuthenticateResponse' '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: invalid_organization_id const: invalid_organization_id 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: code_challenge_not_found const: code_challenge_not_found 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_credentials const: invalid_credentials 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_one_time_code const: invalid_one_time_code 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: one_time_code_previously_used const: one_time_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: one_time_code_expired const: one_time_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: one_time_code_too_many_attempts const: one_time_code_too_many_attempts 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_pending_authentication_token const: invalid_pending_authentication_token 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: user_mismatch const: user_mismatch message: type: string description: A human-readable description of the error. example: Request could not be processed. required: - code - message - type: object properties: error: type: string description: The OAuth error code. example: invalid_client const: invalid_client error_description: type: string description: A human-readable description of the error. example: 'The request failed due to: invalid_client.' required: - error - error_description - type: object properties: error: type: string description: The OAuth error code. example: unauthorized_client const: unauthorized_client error_description: type: string description: A human-readable description of the error. example: 'The request failed due to: unauthorized_client.' required: - error - error_description - type: object properties: error: type: string description: The OAuth error code. example: invalid_profile const: invalid_profile error_description: type: string description: A human-readable description of the error. example: 'The request failed due to: invalid_profile.' required: - error - error_description - 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: type: string description: The OAuth error code. example: invitation_cannot_be_used_for_email const: invitation_cannot_be_used_for_email error_description: type: string description: A human-readable description of the error. example: >- The request failed due to: invitation_cannot_be_used_for_email. required: - error - error_description - type: object properties: error: type: string 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: >- The request failed due to: authentication_method_not_allowed. required: - error - error_description - type: object properties: error: type: string description: The OAuth error code. example: invalid_connection const: invalid_connection error_description: type: string description: A human-readable description of the error. example: 'The request failed due to: invalid_connection.' required: - error - error_description - type: object properties: error: type: string 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: 'The request failed due to: sign_up_not_allowed.' required: - error - error_description - type: object properties: error: type: string description: The OAuth error code. example: organization_authentication_methods_required const: organization_authentication_methods_required error_description: type: string description: A human-readable description of the error. example: >- The request failed due to: organization_authentication_methods_required. required: - error - error_description - type: object properties: error: type: string description: The OAuth error code. example: invalid_link_authorization_code const: invalid_link_authorization_code error_description: type: string description: A human-readable description of the error. example: >- The request failed due to: invalid_link_authorization_code. required: - error - error_description - type: object properties: error: type: string description: The OAuth error code. example: extra_attributes_required const: extra_attributes_required error_description: type: string description: A human-readable description of the error. example: 'The request failed due to: extra_attributes_required.' required: - error - error_description - type: object properties: error: type: string description: The OAuth error code. example: pkce_not_supported const: pkce_not_supported error_description: type: string description: A human-readable description of the error. example: 'The request failed due to: pkce_not_supported.' required: - error - error_description - type: object properties: error: type: string description: The OAuth error code. example: expired_token const: expired_token error_description: type: string description: A human-readable description of the error. example: 'The request failed due to: expired_token.' required: - error - error_description - type: object properties: error: type: string description: The OAuth error code. example: authorization_pending const: authorization_pending error_description: type: string description: A human-readable description of the error. example: 'The request failed due to: authorization_pending.' required: - error - error_description - type: object properties: error: type: string description: The OAuth error code. example: access_denied const: access_denied error_description: type: string description: A human-readable description of the error. example: 'The request failed due to: access_denied.' required: - error - error_description - type: object properties: error: type: string description: The OAuth error code. example: slow_down const: slow_down error_description: type: string description: A human-readable description of the error. example: 'The request failed due to: slow_down.' required: - error - error_description - type: object properties: message: type: string const: Must use SSO for selected organization required: - message - oneOf: - type: object properties: error: type: string description: The OAuth error code. example: invalid_grant const: invalid_grant error_description: type: string description: A human-readable description of the error. example: 'The request failed due to: invalid_grant.' required: - error - error_description - type: object properties: error: type: string description: The OAuth error code. example: invalid_request const: invalid_request error_description: type: string description: A human-readable description of the error. example: 'The request failed due to: invalid_request.' required: - error - error_description - type: object properties: error: type: string description: The OAuth error code. example: organization_not_found const: organization_not_found error_description: type: string description: A human-readable description of the error. example: 'The request failed due to: organization_not_found.' required: - error - error_description - type: object properties: error: type: string description: The OAuth error code. example: organization_membership_not_found const: organization_membership_not_found error_description: type: string description: A human-readable description of the error. example: >- The request failed due to: organization_membership_not_found. required: - error - error_description - type: object properties: error: type: string description: The OAuth error code. example: mfa_enrollment const: mfa_enrollment error_description: type: string description: A human-readable description of the error. example: 'The request failed due to: mfa_enrollment.' required: - error - error_description - type: object properties: error: type: string description: The OAuth error code. example: token_too_big const: token_too_big error_description: type: string description: A human-readable description of the error. example: 'The request failed due to: token_too_big.' required: - error - error_description - allOf: - type: object properties: error: type: string description: The OAuth error code. example: sso_required const: sso_required error_description: type: string description: A human-readable description of the error. example: 'The request failed due to: sso_required.' required: - error - error_description - type: object properties: connection_ids: type: array items: type: string example: conn_01FVYZ... description: >- The IDs of the SSO connections the user must authenticate through. email: type: string description: >- The email address of the user that must authenticate via SSO. example: user@example.com required: - connection_ids - email '403': description: Forbidden content: application/json: schema: oneOf: - type: object properties: code: type: string description: The error code identifying the type of error. example: mfa_enrollment const: mfa_enrollment 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: mfa_challenge const: mfa_challenge 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: authentication_method_not_allowed const: authentication_method_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_verification_required const: email_verification_required 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_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: organization_selection_required const: organization_selection_required 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: passkey_progressive_enrollment const: passkey_progressive_enrollment 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: radar_challenge const: radar_challenge 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: radar_sign_up_challenge const: radar_sign_up_challenge 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: application_consent_required const: application_consent_required message: type: string description: A human-readable description of the error. example: Request could not be processed. required: - code - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '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 '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 summary: Authenticate tags: - user-management.authentication /user_management/authorize: get: description: >- Generates an OAuth 2.0 authorization URL to authenticate a user with AuthKit or SSO. operationId: UserlandSsoController_authorize parameters: - name: code_challenge_method required: false in: query schema: type: string example: S256 const: S256 description: >- The only valid PKCE code challenge method is `"S256"`. Required when specifying a `code_challenge`. - name: code_challenge required: false in: query schema: type: string example: E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM description: >- Code challenge derived from the code verifier used for the PKCE flow. - name: domain_hint required: false in: query schema: type: string example: example.com description: A domain hint for SSO connection lookup. - name: connection_id required: false in: query schema: type: string example: conn_01EHQMYV6MBK39QC5PZXHY59C3 description: The ID of an SSO connection to use for authentication. - name: provider_query_params required: false in: query schema: type: object additionalProperties: type: string example: hd: example.com access_type: offline description: Key/value pairs of query parameters to pass to the OAuth provider. - name: provider_scopes required: false in: query style: form explode: false schema: type: array items: type: string example: - openid - profile - email description: Additional OAuth scopes to request from the identity provider. - name: invitation_token required: false in: query schema: type: string example: inv_token_abc123 description: >- A token representing a user invitation to redeem during authentication. - name: screen_hint required: false in: query schema: type: string enum: - sign-up - sign-in default: sign-in example: sign-in description: >- Used to specify which screen to display when the provider is `authkit`. - name: login_hint required: false in: query schema: type: string example: user@example.com description: >- A hint to the authorization server about the login identifier the user might use. - name: provider required: false in: query schema: type: string enum: - authkit - AppleOAuth - BitbucketOAuth - GitHubOAuth - GitLabOAuth - GoogleOAuth - IntuitOAuth - LinkedInOAuth - MicrosoftOAuth - SalesforceOAuth - SlackOAuth - VercelMarketplaceOAuth - VercelOAuth - XeroOAuth example: GoogleOAuth description: >- The OAuth provider to authenticate with (e.g., GoogleOAuth, MicrosoftOAuth, GitHubOAuth). - name: prompt required: false in: query schema: type: string example: login description: Controls the authentication flow behavior for the user. - name: state required: false in: query schema: type: string example: eyJyZXR1cm5UbyI6ICIvZGFzaGJvYXJkIn0= description: >- An opaque value used to maintain state between the request and the callback. - name: organization_id required: false in: query schema: type: string example: org_01EHQMYV6MBK39QC5PZXHY59C3 description: The ID of the organization to authenticate the user against. - name: response_type required: true in: query schema: type: string example: code const: code description: The response type of the application. - name: redirect_uri required: true in: query schema: type: string format: uri example: https://example.com/callback description: >- The callback URI where the authorization code will be sent after authentication. - name: client_id required: true in: query schema: type: string example: client_01HZBC6N1EB1ZY7KG32X description: The unique identifier of the WorkOS environment client. responses: '200': headers: location: schema: type: string format: uri description: OK '302': headers: location: schema: type: string format: uri description: '' security: [] summary: Get an authorization URL tags: - user-management.authentication /user_management/authorize/device: post: description: >- Initiates the CLI Auth flow by requesting a device code and verification URLs. This endpoint implements the OAuth 2.0 Device Authorization Flow ([RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628)) and is designed for command-line applications or other devices with limited input capabilities. operationId: UserlandSsoController_deviceAuthorization parameters: [] requestBody: required: true content: application/json: schema: type: object properties: client_id: type: string description: The WorkOS client ID for your application. example: client_01HZBC6N1EB1ZY7KG32X required: - client_id responses: '200': description: Device authorization response with codes and verification URI. content: application/json: schema: $ref: '#/components/schemas/DeviceAuthorizationResponse' '400': description: Invalid request parameters. content: application/json: schema: type: object properties: error: type: string description: Error code. example: invalid_client error_description: type: string description: Human-readable error description. example: Unknown client required: - error - error_description '403': description: Feature not enabled for team. content: application/json: schema: type: object properties: error: type: string description: Error code. example: access_denied error_description: type: string description: Human-readable error description. example: Device authorization grant is not enabled for this team required: - error - error_description security: [] summary: Get device authorization URL tags: - user-management.authentication /user_management/cors_origins: post: description: >- Creates a new CORS origin for the current environment. CORS origins allow browser-based applications to make requests to the WorkOS API. operationId: CorsOriginsController_createCorsOrigin parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCorsOriginDto' 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: code: type: string description: The error code. example: duplicate_cors_origin message: type: string description: A human-readable error message. example: CORS origin already exists. '422': description: Validation error. content: application/json: schema: type: object properties: message: type: string description: A human-readable error message. example: Validation failed. errors: type: array description: The list of validation errors. items: type: object properties: property: type: string description: The property that failed validation. example: origin constraints: type: object summary: Create a CORS origin tags: - user-management.cors-origins /user_management/email_verification/{id}: get: description: >- Get the details of an existing email verification code that can be used to send an email to a user for verification. operationId: UserlandUsersController_getEmailVerification parameters: - name: id required: true in: path description: The ID of the email verification code. schema: type: string example: email_verification_01E4ZCR3C56J083X43JQXF3JK5 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/EmailVerification' '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Get an email verification code tags: - user-management.users /user_management/invitations: get: description: Get a list of all of invitations matching the criteria specified. operationId: UserlandUserInvitesController_list parameters: - name: before required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `before="obj_123"` to fetch a new batch of objects before `"obj_123"`. schema: example: xxx_01HXYZ123456789ABCDEFGHIJ type: string - name: after required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `after="obj_123"` to fetch a new batch of objects after `"obj_123"`. schema: example: xxx_01HXYZ987654321KJIHGFEDCBA type: string - name: limit required: false in: query description: >- Upper limit on the number of objects to return, between `1` and `100`. schema: minimum: 1 maximum: 100 default: 10 example: 10 type: integer - name: order required: false in: query description: >- Order the results by the creation time. Supported values are `"asc"` (ascending), `"desc"` (descending), and `"normal"` (descending with reversed cursor semantics where `before` fetches older records and `after` fetches newer records). schema: $ref: '#/components/schemas/PaginationOrder' - name: organization_id required: false in: query description: >- The ID of the [organization](/reference/organization) that the recipient will join. schema: example: org_01E4ZCR3C56J083X43JQXF3JK5 type: string - name: email required: false in: query description: The email address of the recipient. schema: format: email example: marcelina.davis@example.com 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: invitation_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: invitation_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/UserlandUserInvite' '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 summary: List invitations tags: - user-management.invitations post: description: Sends an invitation email to the recipient. operationId: UserlandUserInvitesController_create parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateUserlandUserInviteOptionsDto' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/UserlandUserInvite' '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_already_invited_to_organization const: email_already_invited_to_organization 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: user_already_organization_member const: user_already_organization_member 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_invited const: email_already_invited 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: user_already_exists const: user_already_exists 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: expires_in_days_too_short const: expires_in_days_too_short 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: expires_in_days_too_long const: expires_in_days_too_long 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_role const: invalid_role message: type: string description: A human-readable description of the error. example: Request could not be processed. required: - code - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '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 summary: Send an invitation tags: - user-management.invitations x-sends-email: true /user_management/invitations/by_token/{token}: get: description: Retrieve an existing invitation using the token. operationId: UserlandUserInvitesController_getByToken parameters: - name: token required: true in: path description: The token used to accept the invitation. schema: example: Z1uX3RbwcIl5fIGJJJCXXisdI type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/UserlandUserInvite' '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Find an invitation by token tags: - user-management.invitations /user_management/invitations/{id}: get: description: Get the details of an existing invitation. operationId: UserlandUserInvitesController_get 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: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Get an invitation tags: - user-management.invitations /user_management/invitations/{id}/accept: post: description: >- Accepts an invitation and, if linked to an organization, activates the user's membership in that organization. operationId: UserlandUserInvitesController_accept 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: 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: accepted accepted_at: format: date-time type: - string - 'null' description: >- The timestamp when the invitation was accepted, or null if not yet accepted. example: '2026-01-15T12:00:00.000Z' 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_01HYGBX8ZGD19949T3BM4FW1C3 accepted_user_id: type: - string - 'null' description: >- The ID of the user who accepted the invitation, once accepted. example: user_01E4ZCR3C56J083X43JQXF3JK5 role_slug: type: - string - 'null' description: >- Slug of the role the invitee will be assigned on acceptance. Reflects the current role on the invitee's organization membership. null when the invitation has no associated organization. example: admin 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 - role_slug - created_at - 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: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Accept an invitation tags: - user-management.invitations /user_management/invitations/{id}/resend: post: description: >- Resends an invitation email to the recipient. The invitation must be in a pending state. operationId: UserlandUserInvitesController_resend 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 summary: Resend an invitation tags: - user-management.invitations x-sends-email: true /user_management/invitations/{id}/revoke: post: description: Revokes an existing invitation. operationId: UserlandUserInvitesController_revoke 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: 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_01HYGBX8ZGD19949T3BM4FW1C3 accepted_user_id: type: - string - 'null' description: >- The ID of the user who accepted the invitation, once accepted. example: null role_slug: type: - string - 'null' description: >- Slug of the role the invitee will be assigned on acceptance. Reflects the current role on the invitee's organization membership. null when the invitation has no associated organization. example: admin 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 - role_slug - created_at - 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 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. example: Invite is not pending. required: - code - message summary: Revoke an invitation tags: - user-management.invitations /user_management/jwt_template: get: description: Get the JWT template for the current environment. operationId: JwtTemplatesController_getJwtTemplate parameters: [] responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/JwtTemplate' '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Get JWT template tags: - user-management.jwt-template put: description: Update the JWT template for the current environment. operationId: JwtTemplatesController_updateJwtTemplate parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateJwtTemplateDto' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/JwtTemplate' '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 summary: Update JWT template tags: - user-management.jwt-template /user_management/magic_auth: post: 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). operationId: UserlandMagicAuthController_sendMagicAuthCodeAndReturn parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateUserlandMagicCodeAndReturnDto' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/MagicAuth' '400': description: Bad Request content: application/json: schema: 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: type: string 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: >- The request failed due to: authentication_method_not_allowed. required: - error - error_description - type: object properties: error: type: string 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: 'The request failed due to: sign_up_not_allowed.' required: - error - error_description '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 '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 summary: Create a Magic Auth code tags: - user-management.magic-auth x-sends-email: true /user_management/magic_auth/{id}: get: 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. operationId: UserlandMagicAuthController_get parameters: - name: id required: true in: path description: The unique ID of the Magic Auth code. schema: 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: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Get Magic Auth code details tags: - user-management.magic-auth /user_management/organization_memberships: get: 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. operationId: UserlandUserOrganizationMembershipsController_list parameters: - name: before required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `before="obj_123"` to fetch a new batch of objects before `"obj_123"`. schema: example: xxx_01HXYZ123456789ABCDEFGHIJ type: string - name: after required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `after="obj_123"` to fetch a new batch of objects after `"obj_123"`. schema: example: xxx_01HXYZ987654321KJIHGFEDCBA type: string - name: limit required: false in: query description: >- Upper limit on the number of objects to return, between `1` and `100`. schema: minimum: 1 maximum: 100 default: 10 example: 10 type: integer - name: order required: false in: query description: >- Order the results by the creation time. Supported values are `"asc"` (ascending), `"desc"` (descending), and `"normal"` (descending with reversed cursor semantics where `before` fetches older records and `after` fetches newer records). schema: $ref: '#/components/schemas/PaginationOrder' - 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: $ref: >- #/components/schemas/UserlandUserOrganizationMembership '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: invalid_request_parameters const: invalid_request_parameters message: type: string description: A human-readable description of the error. example: Validation failed. required: - code - message - type: object properties: 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 message: type: string description: A human-readable description of the error. example: Request could not be processed. required: - code - message '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: List organization memberships tags: - user-management.organization-membership post: 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). operationId: UserlandUserOrganizationMembershipsController_create parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateUserlandUserOrganizationMembershipDto' 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_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E organization_id: type: string description: The ID of the organization which the user belongs to. example: org_01E4ZCR3C56J083X43JQXF3JK5 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. user: $ref: '#/components/schemas/UserlandUser' description: >- The user that belongs to the organization through this membership. required: - object - id - user_id - organization_id - status - directory_managed - created_at - updated_at - role - user 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 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: oneOf: - 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 - 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: 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 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 summary: Create an organization membership tags: - user-management.organization-membership x-mutually-exclusive-body-groups: &ref_9 role: optional: true variants: single: - role_slug multiple: - role_slugs /user_management/organization_memberships/{id}: get: description: Get the details of an existing organization membership. operationId: UserlandUserOrganizationMembershipsController_get 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: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Get an organization membership tags: - user-management.organization-membership delete: description: >- Permanently deletes an existing organization membership. It cannot be undone. operationId: UserlandUserOrganizationMembershipsController_delete 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: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Delete an organization membership tags: - user-management.organization-membership put: description: Update the details of an existing organization membership. operationId: UserlandUserOrganizationMembershipsController_update 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: 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: oneOf: - 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 - 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: 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 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 summary: Update an organization membership tags: - user-management.organization-membership x-mutually-exclusive-body-groups: &ref_10 role: optional: true variants: single: - role_slug multiple: - role_slugs /user_management/organization_memberships/{id}/deactivate: put: 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. operationId: UserlandUserOrganizationMembershipsController_deactivate 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: 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_01E4ZCR3C56J083X43JQXF3JK5 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: inactive 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. user: $ref: '#/components/schemas/UserlandUser' description: >- The user that belongs to the organization through this membership. required: - object - id - user_id - organization_id - status - directory_managed - created_at - updated_at - role - user 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 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 - code '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 summary: Deactivate an organization membership tags: - user-management.organization-membership /user_management/organization_memberships/{id}/reactivate: put: 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. operationId: UserlandUserOrganizationMembershipsController_reactivate 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' '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 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 summary: Reactivate an organization membership tags: - user-management.organization-membership /user_management/organization_memberships/{omId}/groups: get: description: Get a list of groups that an organization membership belongs to. operationId: OrganizationMembershipGroupsController_listGroups parameters: - name: omId required: true in: path description: Unique identifier of the Organization Membership. schema: type: string example: om_01HXYZ123456789ABCDEFGHIJ - name: before required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `before="obj_123"` to fetch a new batch of objects before `"obj_123"`. schema: example: xxx_01HXYZ123456789ABCDEFGHIJ type: string - name: after required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `after="obj_123"` to fetch a new batch of objects after `"obj_123"`. schema: example: xxx_01HXYZ987654321KJIHGFEDCBA type: string - name: limit required: false in: query description: >- Upper limit on the number of objects to return, between `1` and `100`. schema: minimum: 1 maximum: 100 default: 10 example: 10 type: integer - name: order required: false in: query description: >- Order the results by the creation time. Supported values are `"asc"` (ascending), `"desc"` (descending), and `"normal"` (descending with reversed cursor semantics where `before` fetches older records and `after` fetches newer records). schema: $ref: '#/components/schemas/PaginationOrder' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/GroupList' '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: List groups tags: - user-management.organization-membership.groups x-feature-flag: user-groups-enabled /user_management/password_reset: post: description: Creates a one-time token that can be used to reset a user's password. operationId: UserlandUsersController_createPasswordResetToken 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: 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''.' 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 '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 summary: Create a password reset token tags: - user-management.users x-sends-email: true /user_management/password_reset/confirm: post: 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_resetPassword[0] 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: 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 '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 summary: Reset the password tags: - user-management.users /user_management/password_reset/{id}: get: description: >- Get the details of an existing password reset token that can be used to reset a user's password. operationId: UserlandUsersController_getPasswordReset parameters: - name: id required: true in: path description: The ID of the password reset token. schema: 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: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Get a password reset token tags: - user-management.users /user_management/redirect_uris: post: description: Creates a new redirect URI for an environment. operationId: RedirectUrisController_create 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: 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. summary: Create a redirect URI tags: - user-management.redirect-uris /user_management/sessions/logout: get: description: Logout a user from the current [session](/reference/authkit/session). operationId: UserlandSessionsController_logout parameters: - name: session_id required: true in: query description: >- The ID of the session. 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 logout. 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: 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 security: [] summary: Logout tags: - user-management.authentication /user_management/sessions/revoke: post: description: Revoke a [user session](/reference/authkit/session). operationId: UserlandSessionsController_revokeSession parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UserlandRevokeSessionDto' responses: '200': description: OK '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 summary: Revoke Session tags: - user-management.authentication /user_management/users: get: description: >- Get a list of all of your existing users matching the criteria specified. operationId: UserlandUsersController_list[0] parameters: - name: before required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `before="obj_123"` to fetch a new batch of objects before `"obj_123"`. schema: example: xxx_01HXYZ123456789ABCDEFGHIJ type: string - name: after required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `after="obj_123"` to fetch a new batch of objects after `"obj_123"`. schema: example: xxx_01HXYZ987654321KJIHGFEDCBA type: string - name: limit required: false in: query description: >- Upper limit on the number of objects to return, between `1` and `100`. schema: minimum: 1 maximum: 100 default: 10 example: 10 type: integer - name: order required: false in: query description: >- Order the results by the creation time. Supported values are `"asc"` (ascending), `"desc"` (descending), and `"normal"` (descending with reversed cursor semantics where `before` fetches older records and `after` fetches newer records). schema: $ref: '#/components/schemas/PaginationOrder' - 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: $ref: '#/components/schemas/UserlandUserList' '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: List users tags: - user-management.users post: description: Create a new user in the current environment. operationId: UserlandUsersController_create[0] parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateUserlandUserDto' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/UserlandUser' '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: 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: 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 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: 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 summary: Create a user tags: - user-management.users x-mutually-exclusive-body-groups: &ref_11 password: optional: true variants: plaintext: - password hashed: - password_hash - password_hash_type /user_management/users/external_id/{external_id}: get: description: >- Get the details of an existing user by an [external identifier](/authkit/metadata/external-identifiers). operationId: UserlandUsersController_getByExternalId parameters: - name: external_id required: true in: path description: The external ID of the user. schema: example: f1ffa2b2-c20b-4d39-be5c-212726e11222 type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/UserlandUser' '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Get a user by external ID tags: - user-management.users /user_management/users/{id}: put: description: >- Updates properties of a user. The omitted properties will be left unchanged. operationId: UserlandUsersController_update[0] 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/UpdateUserlandUserDto' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/UserlandUser' '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: 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: 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 summary: Update a user tags: - user-management.users x-mutually-exclusive-body-groups: &ref_14 password: optional: true variants: plaintext: - password hashed: - password_hash - password_hash_type get: description: Get the details of an existing user. operationId: UserlandUsersController_get[0] parameters: - name: id required: true in: path description: The unique ID of the user. schema: example: user_01E4ZCR3C56J083X43JQXF3JK5 type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/UserlandUser' '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Get a user tags: - user-management.users delete: description: >- Permanently deletes a user in the current environment. It cannot be undone. operationId: UserlandUsersController_delete[0] parameters: - name: id required: true in: path description: The unique ID of the user. schema: example: user_01E4ZCR3C56J083X43JQXF3JK5 type: string responses: '200': description: OK '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Delete a user tags: - user-management.users /user_management/users/{id}/email_change/confirm: post: description: Confirms an email change using the one-time code received by the user. operationId: UserlandUsersController_confirmEmailChange 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/ConfirmEmailChangeDto' responses: '200': description: OK content: application/json: schema: type: object properties: object: type: string description: Distinguishes the email change confirmation object. const: email_change_confirmation 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 name: type: - string - 'null' description: The user's full name. example: Marcelina 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: new.email@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 object. required: - object - user x-inline-with-overrides: true '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_change_code_expired const: email_change_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_change_code_incorrect const: email_change_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 content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '409': description: '' content: application/json: schema: oneOf: - type: object properties: code: type: string description: The error code identifying the type of error. example: no_pending_email_change const: no_pending_email_change 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_code_previously_used const: email_change_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_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: 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 '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_request_parameters const: invalid_request_parameters message: type: string description: A human-readable description of the error. example: Validation failed. 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 '429': description: '' content: application/json: schema: type: object properties: code: type: string description: The error code identifying the type of error. example: email_change_too_many_attempts const: email_change_too_many_attempts message: type: string description: A human-readable description of the error. example: Request could not be processed. required: - code - message summary: Confirm email change tags: - user-management.users /user_management/users/{id}/email_change/send: post: description: >- Sends an email that contains a one-time code used to change a user's email address. operationId: UserlandUsersController_sendEmailChange 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/SendEmailChangeDto' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/EmailChange' '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '409': description: '' content: application/json: schema: oneOf: - type: object properties: code: type: string description: The error code identifying the type of error. example: email_change_not_needed const: email_change_not_needed 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: 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 '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_request_parameters const: invalid_request_parameters message: type: string description: A human-readable description of the error. example: Validation failed. 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 '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 summary: Send email change code tags: - user-management.users x-sends-email: true /user_management/users/{id}/email_verification/confirm: post: description: Verifies an email address using the one-time code received by the user. operationId: UserlandUsersController_emailVerification[0] 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/VerifyEmailAddressDto' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/VerifyEmailResponse' '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 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 summary: Verify email tags: - user-management.users /user_management/users/{id}/email_verification/send: post: description: >- Sends an email that contains a one-time code used to verify a user’s email address. operationId: UserlandUsersController_sendVerificationEmail[0] parameters: - name: id required: true in: path description: The ID of the user. schema: 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: 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 '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 '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 summary: Send verification email tags: - user-management.users /user_management/users/{id}/identities: get: 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. operationId: UserlandUserIdentitiesController_get parameters: - name: id required: true in: path description: The unique ID of the 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 content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Get user identities tags: - user-management.users /user_management/users/{id}/sessions: get: description: Get a list of all active sessions for a specific user. operationId: UserlandUserSessionsController_list 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: integer - name: order required: false in: query description: >- Order the results by the creation time. Supported values are `"asc"` (ascending), `"desc"` (descending), and `"normal"` (descending with reversed cursor semantics where `before` fetches older records and `after` fetches newer records). schema: $ref: '#/components/schemas/PaginationOrder' 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: 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: object: type: string 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: >- 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: - 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: 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 summary: List sessions tags: - user-management.users /user_management/users/{userId}/api_keys: get: description: Get a list of API keys owned by a specific user. operationId: UserApiKeysController_list parameters: - name: userId required: true in: path description: Unique identifier 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. 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: integer - name: order required: false in: query description: Order the results by the creation time. schema: $ref: '#/components/schemas/PaginationOrder' - name: organization_id required: false in: query description: >- The ID of the organization to filter user API keys by. When provided, only API keys created against that organization membership are returned. schema: example: org_01EHZNVPK3SFK441A1RGBFSHRT type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/UserApiKeyList' '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: List API keys for a user tags: - api_keys x-feature-flag: user-api-keys post: description: >- Create a new API key owned by a user. The user must have an active membership in the specified organization. operationId: UserApiKeysController_create parameters: - name: userId required: true in: path description: Unique identifier of the user. schema: type: string example: user_01EHZNVPK3SFK441A1RGBFSHRT requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateUserApiKeyDto' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/UserApiKeyWithValue' '400': description: Bad Request 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 properties: code: type: string description: The validation error code. example: required field: type: string description: The field that failed validation. example: event.action required: - code - field description: The list of validation errors. required: - message - errors '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Create an API key for a user tags: - api_keys x-feature-flag: user-api-keys /user_management/users/{userId}/feature-flags: get: 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. operationId: UserlandUserFeatureFlagsController_list 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: integer - name: order required: false in: query description: Order the results by the creation time. schema: $ref: '#/components/schemas/PaginationOrder' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/FlagList' '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: List enabled feature flags for a user tags: - user-management.users.feature-flags /user_management/users/{user_id}/authorized_applications: get: description: Get a list of all Connect applications that the user has authorized. operationId: AuthorizedApplicationsController_list 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: integer - name: order required: false in: query description: >- Order the results by the creation time. Supported values are `"asc"` (ascending), `"desc"` (descending), and `"normal"` (descending with reversed cursor semantics where `before` fetches older records and `after` fetches newer records). schema: $ref: '#/components/schemas/PaginationOrder' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AuthorizedConnectApplicationList' '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: List authorized applications tags: - user-management.users.authorized-applications /user_management/users/{user_id}/authorized_applications/{application_id}: delete: description: Delete an existing Authorized Connect Application. operationId: AuthorizedApplicationsController_delete 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 summary: Delete an authorized application tags: - user-management.users.authorized-applications /user_management/users/{user_id}/connected_accounts/{slug}: get: description: >- Retrieves a user's [connected account](/reference/pipes/connected-account) for a specific provider. operationId: DataIntegrationsUserManagementController_getUserDataInstallation 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: '200': description: The connected account was retrieved successfully. content: application/json: schema: $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: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Get a connected account tags: - user-management.data-providers delete: 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. operationId: DataIntegrationsUserManagementController_deleteUserDataInstallation 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: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Delete a connected account tags: - user-management.data-providers /user_management/users/{user_id}/data_providers: get: 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. operationId: DataIntegrationsUserManagementController_getUserDataIntegrations parameters: - name: user_id required: true in: path description: >- A [User](/reference/authkit/user) identifier to list providers and connected accounts for. schema: 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: The list of data providers was retrieved successfully. content: application/json: schema: $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: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: List providers tags: - user-management.data-providers /user_management/users/{userlandUserId}/auth_factors: post: description: >- Enrolls a user in a new [authentication factor](/reference/authkit/mfa/authentication-factor). operationId: UserlandUserAuthenticationFactorsController_create[0] 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: $ref: >- #/components/schemas/UserlandUserAuthenticationFactorEnrollResponse '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Enroll an authentication factor tags: - user-management.multi-factor-authentication get: description: >- Lists the [authentication factors](/reference/authkit/mfa/authentication-factor) for a user. operationId: UserlandUserAuthenticationFactorsController_list[0] parameters: - name: userlandUserId required: true in: path description: The ID of the [user](/reference/authkit/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: integer - name: order required: false in: query description: Order the results by the creation time. schema: $ref: '#/components/schemas/PaginationOrder' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/UserlandUserAuthenticationFactorList' '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: List authentication factors tags: - user-management.multi-factor-authentication /vault/v1/keys/data-key: post: description: Generate an isolated encryption key for local encryption operations. operationId: JumpWireWeb.KeyController.create_data_key parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateDataKeyRequest' description: Data key request. required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/CreateDataKeyResponse' description: Data key. '400': content: application/json: schema: $ref: '#/components/schemas/Error' description: Bad request. '422': content: application/json: schema: $ref: '#/components/schemas/Error' description: Validation error. summary: Create a data key tags: - vault /vault/v1/keys/decrypt: post: description: Decrypt a previously encrypted data key from WorkOS Vault. operationId: JumpWireWeb.KeyController.decrypt parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/DecryptRequest' description: Decrypt request. required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/DecryptResponse' description: Decrypted key. '400': content: application/json: schema: $ref: '#/components/schemas/Error' description: Bad request. summary: Decrypt a data key tags: - vault /vault/v1/keys/rekey: post: description: Decrypt an existing data key and re-encrypt it under a new key context. operationId: JumpWireWeb.KeyController.rekey parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/RekeyRequest' description: Rekey request. required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/CreateDataKeyResponse' description: Re-encrypted key. '400': content: application/json: schema: $ref: '#/components/schemas/Error' description: Bad request. '422': content: application/json: schema: $ref: '#/components/schemas/Error' description: Validation error. summary: Re-encrypt a data key tags: - vault /vault/v1/kv: get: description: List all encrypted objects with cursor-based pagination. operationId: JumpWireWeb.DataVaultController.index parameters: - description: Upper limit on the number of objects to return. in: query name: limit required: false schema: default: 10 example: 10 minimum: 1 type: integer - description: Cursor for the previous page of results. in: query name: before required: false schema: example: b21f3a8c-7e4d-4b1a-9c5e-2d8f6a7b3c4e type: string - description: Cursor for the next page of results. in: query name: after required: false schema: example: a10e2b7d-6c3f-4a2b-8d1e-3f9a5b8c7d6e type: string - description: Sort direction for results. in: query name: order required: false schema: enum: - asc - desc example: desc type: string - description: Filter results by name or structured search JSON. in: query name: search required: false schema: example: my-secret type: string - description: ISO 8601 timestamp to filter by last modified time. in: query name: updatedAfter required: false schema: example: '2024-01-01T00:00:00Z' format: date-time type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/ObjectListResponse' description: Object list. '400': content: application/json: schema: $ref: '#/components/schemas/Error' description: Bad request. summary: List objects tags: - vault post: description: Encrypt and store a new key-value object. operationId: JumpWireWeb.DataVaultController.create parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateObjectRequest' description: Create object. required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/ObjectMetadata' description: Object created. '400': content: application/json: schema: $ref: '#/components/schemas/Error' description: Bad request. '409': content: application/json: schema: $ref: '#/components/schemas/Error' description: Conflict. '422': content: application/json: schema: $ref: '#/components/schemas/Error' description: Validation error. summary: Create an object tags: - vault /vault/v1/kv/name/{name}: get: description: Fetch and decrypt an object by its unique name. operationId: JumpWireWeb.DataVaultController.show_by_name parameters: - description: Unique name of the object. in: path name: name required: true schema: example: my-secret type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/Object' description: Object. '400': content: application/json: schema: $ref: '#/components/schemas/Error' description: Bad request. '404': content: application/json: schema: $ref: '#/components/schemas/Error' description: Not found. summary: Read an object by name tags: - vault /vault/v1/kv/{id}: delete: description: Delete an encrypted object. operationId: JumpWireWeb.DataVaultController.delete parameters: - description: Unique identifier of the object. in: path name: id required: true schema: example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 type: string - description: Expected current version for optimistic locking. in: query name: version_check required: false schema: example: c3d4e5f6-7890-abcd-ef12-34567890abcd type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/DeleteObjectResponse' description: Deletion result. '404': content: application/json: schema: $ref: '#/components/schemas/Error' description: Not found. '409': content: application/json: schema: $ref: '#/components/schemas/Error' description: Version mismatch. '500': content: application/json: schema: $ref: '#/components/schemas/Error' description: Internal error. summary: Delete an object tags: - vault get: description: Fetch and decrypt an object by its unique identifier. operationId: JumpWireWeb.DataVaultController.show_by_id parameters: - description: Unique identifier of the object. in: path name: id required: true schema: example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/Object' description: Object. '400': content: application/json: schema: $ref: '#/components/schemas/Error' description: Bad request. '404': content: application/json: schema: $ref: '#/components/schemas/Error' description: Not found. summary: Read an object by ID tags: - vault put: description: Update the value of an existing encrypted object. operationId: JumpWireWeb.DataVaultController.update parameters: - description: Unique identifier of the object. in: path name: id required: true schema: example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateObjectRequest' description: Update object. required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/ObjectWithoutValue' description: Object updated. '400': content: application/json: schema: $ref: '#/components/schemas/Error' description: Bad request. '409': content: application/json: schema: $ref: '#/components/schemas/Error' description: Version mismatch. summary: Update an object tags: - vault /vault/v1/kv/{id}/metadata: get: description: Fetch metadata for an object without decrypting it. operationId: JumpWireWeb.DataVaultController.describe parameters: - description: Unique identifier of the object. in: path name: id required: true schema: example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/ObjectWithoutValue' description: Object metadata. '400': content: application/json: schema: $ref: '#/components/schemas/Error' description: Bad request. '404': content: application/json: schema: $ref: '#/components/schemas/Error' description: Not found. summary: Describe an object tags: - vault /vault/v1/kv/{id}/versions: get: description: Retrieve all versions for a specific object. operationId: JumpWireWeb.DataVaultController.versions parameters: - description: Unique identifier of the object. in: path name: id required: true schema: example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/VersionListResponse' description: Version list. '400': content: application/json: schema: $ref: '#/components/schemas/Error' description: Bad request. '404': content: application/json: schema: $ref: '#/components/schemas/Error' description: Not found. summary: List object versions tags: - vault /webhook_endpoints: get: description: Get a list of all of your existing webhook endpoints. operationId: WebhookEndpointsController_list parameters: - name: before required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `before="obj_123"` to fetch a new batch of objects before `"obj_123"`. schema: example: xxx_01HXYZ123456789ABCDEFGHIJ type: string - name: after required: false in: query description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `after="obj_123"` to fetch a new batch of objects after `"obj_123"`. schema: example: xxx_01HXYZ987654321KJIHGFEDCBA type: string - name: limit required: false in: query description: >- Upper limit on the number of objects to return, between `1` and `100`. schema: minimum: 1 maximum: 100 default: 10 example: 10 type: integer - name: order required: false in: query description: >- Order the results by the creation time. Supported values are `"asc"` (ascending), `"desc"` (descending), and `"normal"` (descending with reversed cursor semantics where `before` fetches older records and `after` fetches newer records). schema: $ref: '#/components/schemas/PaginationOrder' responses: '200': description: List of webhook endpoints. content: application/json: schema: $ref: '#/components/schemas/WebhookEndpointList' summary: List Webhook Endpoints tags: - webhooks post: description: Create a new webhook endpoint to receive event notifications. operationId: WebhookEndpointsController_create 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: 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 summary: Create a Webhook Endpoint tags: - webhooks /webhook_endpoints/{id}: patch: description: Update the properties of an existing webhook endpoint. operationId: WebhookEndpointsController_update parameters: - name: id required: true in: path description: Unique identifier of the Webhook Endpoint. schema: type: string example: we_0123456789 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateWebhookEndpointDto' responses: '200': description: Webhook endpoint updated successfully. content: application/json: schema: $ref: '#/components/schemas/WebhookEndpointJson' '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 '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 summary: Update a Webhook Endpoint tags: - webhooks delete: description: Delete an existing webhook endpoint. operationId: WebhookEndpointsController_delete 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: 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 summary: Delete a Webhook Endpoint tags: - webhooks /widgets/token: post: description: >- Generate a widget token scoped to an organization and user with the specified scopes. operationId: WidgetsPublicController_issueWidgetSessionToken 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: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: A human-readable description of the error. example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message summary: Generate a widget token tags: - 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: groups description: Organize and manage user groups within organizations. - name: multi-factor-auth description: Multi-factor authentication factor management. - name: multi-factor-auth.challenges description: Multi-factor authentication challenge verification. - name: organization-domains description: Manage organization domains. - 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.organization-membership.groups description: Manage groups for a user organization membership. - 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: vault description: Vault data encryption endpoints. - 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: >- 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 name: type: string description: The user's full name. example: Marcelina 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 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: >- 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 ExpireApiKeyDto: type: object properties: expires_at: type: - string - 'null' description: >- When the API key should expire. If omitted or in the past, the key expires immediately. Use null to clear a scheduled future expiration. example: '2030-01-01T00:00:00.000Z' format: date-time PaginationOrder: type: string enum: - normal - desc - asc example: desc default: desc 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_1 - 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' 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 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_1 type: - array - 'null' items: type: string 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 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_2 ^[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_2 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' format: date-time 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_2 version: type: integer 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: integer 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: minItems: 1 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: allOf: - type: object properties: permission_slug: type: string description: The slug of the permission to check. example: posts:create required: - permission_slug - oneOf: - type: object properties: resource_id: type: string description: >- The ID of the resource. Mutually exclusive with `resource_external_id` and `resource_type_slug`. example: resource_01HXYZ123456789ABCDEFGHIJ required: - resource_id not: anyOf: - properties: resource_external_id: x-exclude-from-lint: true required: - resource_external_id - properties: resource_type_slug: x-exclude-from-lint: true required: - resource_type_slug - type: object properties: resource_external_id: type: string description: >- The external ID of the resource. Required with `resource_type_slug`. Mutually exclusive with `resource_id`. example: my-custom-id resource_type_slug: type: string description: >- The slug of the resource type. Required with `resource_external_id`. Mutually exclusive with `resource_id`. example: document required: - resource_external_id - resource_type_slug not: anyOf: - properties: resource_id: x-exclude-from-lint: true required: - resource_id x-mutually-exclusive-body-groups: *ref_3 AssignRoleDto: allOf: - type: object properties: role_slug: type: string description: The slug of the role to assign. example: editor required: - role_slug - oneOf: - type: object properties: resource_id: type: string description: >- The ID of the resource. Mutually exclusive with `resource_external_id` and `resource_type_slug`. example: authz_resource_01HXYZ123456789ABCDEFGH required: - resource_id not: anyOf: - properties: resource_external_id: x-exclude-from-lint: true required: - resource_external_id - properties: resource_type_slug: x-exclude-from-lint: true required: - resource_type_slug - type: object properties: resource_external_id: type: string description: >- The external ID of the resource. Required with `resource_type_slug`. Mutually exclusive with `resource_id`. example: project-ext-456 resource_type_slug: type: string description: >- The resource type slug. Required with `resource_external_id`. Mutually exclusive with `resource_id`. example: project required: - resource_external_id - resource_type_slug not: anyOf: - properties: resource_id: x-exclude-from-lint: true required: - resource_id x-mutually-exclusive-body-groups: *ref_4 RemoveRoleDto: allOf: - type: object properties: role_slug: type: string description: The slug of the role to remove. example: editor required: - role_slug - oneOf: - type: object properties: resource_id: type: string description: >- The ID of the resource. Mutually exclusive with `resource_external_id` and `resource_type_slug`. example: authz_resource_01HXYZ123456789ABCDEFGH required: - resource_id not: anyOf: - properties: resource_external_id: x-exclude-from-lint: true required: - resource_external_id - properties: resource_type_slug: x-exclude-from-lint: true required: - resource_type_slug - type: object properties: resource_external_id: type: string description: >- The external ID of the resource. Required with `resource_type_slug`. Mutually exclusive with `resource_id`. example: external_01HXYZ123456789ABCDEFGH resource_type_slug: type: string description: >- The resource type slug. Required with `resource_external_id`. Mutually exclusive with `resource_id`. example: project required: - resource_external_id - resource_type_slug not: anyOf: - properties: resource_id: x-exclude-from-lint: true required: - resource_id x-mutually-exclusive-body-groups: *ref_5 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 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. When provided, must begin with 'org-' and contain only lowercase letters, numbers, hyphens, and underscores. When omitted, a slug is auto-generated from the role name and a random suffix. 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 resource_type_slug: type: string maxLength: 48 description: The slug of the resource type the role is scoped to. example: organization required: - name 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: organization 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: allOf: - 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 - oneOf: - type: object not: anyOf: - properties: parent_resource_id: x-exclude-from-lint: true required: - parent_resource_id - properties: parent_resource_external_id: x-exclude-from-lint: true required: - parent_resource_external_id - properties: parent_resource_type_slug: x-exclude-from-lint: true required: - parent_resource_type_slug - type: object properties: parent_resource_id: type: string description: >- The ID of the parent resource. Mutually exclusive with `parent_resource_external_id` and `parent_resource_type_slug`. example: authz_resource_01HXYZ123456789ABCDEFGHIJ required: - parent_resource_id not: anyOf: - properties: parent_resource_external_id: x-exclude-from-lint: true required: - parent_resource_external_id - properties: parent_resource_type_slug: x-exclude-from-lint: true required: - parent_resource_type_slug - type: object properties: parent_resource_external_id: type: string description: >- The external ID of the parent resource. Required with `parent_resource_type_slug`. Mutually exclusive with `parent_resource_id`. example: parent-workspace-01 parent_resource_type_slug: type: string description: >- The resource type slug of the parent resource. Required with `parent_resource_external_id`. Mutually exclusive with `parent_resource_id`. example: workspace required: - parent_resource_external_id - parent_resource_type_slug not: anyOf: - properties: parent_resource_id: x-exclude-from-lint: true required: - parent_resource_id x-mutually-exclusive-body-groups: *ref_0 CreateAuthorizationResourceDto: allOf: - type: object properties: external_id: type: string maxLength: 128 pattern: ^[\x00-\x7F]+$ 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 required: - external_id - name - resource_type_slug - organization_id - oneOf: - type: object not: anyOf: - properties: parent_resource_id: x-exclude-from-lint: true required: - parent_resource_id - properties: parent_resource_external_id: x-exclude-from-lint: true required: - parent_resource_external_id - properties: parent_resource_type_slug: x-exclude-from-lint: true required: - parent_resource_type_slug - type: object properties: parent_resource_id: type: - string - 'null' description: >- The ID of the parent resource. Mutually exclusive with `parent_resource_external_id` and `parent_resource_type_slug`. example: authz_resource_01HXYZ123456789ABCDEFGHIJ required: - parent_resource_id not: anyOf: - properties: parent_resource_external_id: x-exclude-from-lint: true required: - parent_resource_external_id - properties: parent_resource_type_slug: x-exclude-from-lint: true required: - parent_resource_type_slug - type: object properties: parent_resource_external_id: type: string description: >- The external ID of the parent resource. Required with `parent_resource_type_slug`. Mutually exclusive with `parent_resource_id`. example: parent-workspace-01 parent_resource_type_slug: type: string description: >- The resource type slug of the parent resource. Required with `parent_resource_external_id`. Mutually exclusive with `parent_resource_id`. example: workspace required: - parent_resource_external_id - parent_resource_type_slug not: anyOf: - properties: parent_resource_id: x-exclude-from-lint: true required: - parent_resource_id x-mutually-exclusive-body-groups: *ref_6 CreateCorsOriginDto: type: object properties: origin: type: string description: The origin URL to allow for CORS requests. example: https://example.com required: - origin CreateGroupMembershipDto: type: object properties: organization_membership_id: type: string description: The ID of the Organization Membership to add to the group. example: om_01HXYZ123456789ABCDEFGHIJ required: - organization_membership_id CreateGroupDto: type: object properties: name: type: string maxLength: 256 description: The name of the Group. example: Engineering description: type: - string - 'null' maxLength: 150 description: An optional description of the Group. example: The engineering team required: - name UpdateGroupDto: type: object properties: name: type: string maxLength: 256 description: The name of the Group. example: Engineering description: type: - string - 'null' maxLength: 150 description: An optional description of the Group. example: The engineering team UpdateJwtTemplateDto: type: object properties: content: type: string description: The JWT template content as a Liquid template string. example: >- {"urn:myapp:full_name": "{{user.first_name}} {{user.last_name}}", "urn:myapp:email": "{{user.email}}"} 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 expires_at: format: date-time type: string description: >- The timestamp when the API key should expire. Must be a future timestamp. If omitted, the key does not expire. example: '2030-01-01T00:00:00.000Z' 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: >- 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 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_7 type: string maxLength: 600 maxProperties: 50 example: &ref_8 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 pattern: ^[\x00-\x7F]+$ 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_7 maxProperties: 50 example: *ref_8 description: >- Object containing [metadata](/authkit/metadata) key/value pairs associated with the Organization. propertyNames: maxLength: 40 external_id: type: - string - 'null' maxLength: 128 pattern: ^[\x00-\x7F]+$ 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 DomainVerificationIntentOptions: type: object properties: domain_name: type: string description: >- The domain name to verify. When provided, the domain verification flow will skip the domain entry form and go directly to the verification step. example: example.com IntentOptions: type: object properties: sso: description: SSO-specific options for the Admin Portal. $ref: '#/components/schemas/SsoIntentOptions' domain_verification: description: Domain verification-specific options for the Admin Portal. $ref: '#/components/schemas/DomainVerificationIntentOptions' 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' it_contact_emails: description: >- The email addresses of the IT contacts to grant access to the Admin Portal for the given organization. Accepts up to 20 emails. example: - it-contact@example.com maxItems: 20 items: type: string format: email type: array 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 format: email 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 format: email 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: integer 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: >- 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: >- The locale to use when rendering the invitation email. See [supported locales](/authkit/hosted-ui/localization). example: en CreateUserlandUserOrganizationMembershipDto: allOf: - 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 required: - user_id - organization_id - oneOf: - type: object not: anyOf: - properties: role_slug: x-exclude-from-lint: true required: - role_slug - properties: role_slugs: x-exclude-from-lint: true required: - role_slugs - type: object properties: role_slug: type: string description: >- A single role identifier. Defaults to `member` or the explicit default role. Mutually exclusive with `role_slugs`. example: admin required: - role_slug not: anyOf: - properties: role_slugs: x-exclude-from-lint: true required: - role_slugs - type: object properties: role_slugs: description: >- An array of role identifiers. Limited to one role when Multiple Roles is disabled. Mutually exclusive with `role_slug`. example: - admin type: array items: type: string required: - role_slugs not: anyOf: - properties: role_slug: x-exclude-from-lint: true required: - role_slug x-mutually-exclusive-body-groups: *ref_9 UpdateUserlandUserOrganizationMembershipDto: x-mutually-exclusive-body-groups: *ref_10 oneOf: - type: object not: anyOf: - properties: role_slug: x-exclude-from-lint: true required: - role_slug - properties: role_slugs: x-exclude-from-lint: true required: - role_slugs - type: object properties: role_slug: type: string description: >- A single role identifier. Defaults to `member` or the explicit default role. Mutually exclusive with `role_slugs`. example: admin required: - role_slug not: anyOf: - properties: role_slugs: x-exclude-from-lint: true required: - role_slugs - type: object properties: role_slugs: description: >- An array of role identifiers. Limited to one role when Multiple Roles is disabled. Mutually exclusive with `role_slug`. example: - admin type: array items: type: string required: - role_slugs not: anyOf: - properties: role_slug: x-exclude-from-lint: true required: - role_slug CreateUserApiKeyDto: type: object properties: name: type: string description: A descriptive name for the API key. example: Production API Key organization_id: type: string description: >- The ID of the organization the user API key is associated with. The user must have an active membership in this organization. example: org_01EHZNVPK3SFK441A1RGBFSHRT permissions: description: >- The permission slugs to assign to the API key. Each permission must be enabled for user API keys. example: - posts:read - posts:write type: array items: type: string expires_at: format: date-time type: string description: >- The timestamp when the API key should expire. Must be a future timestamp. If omitted, the key does not expire. example: '2030-01-01T00:00:00.000Z' required: - name - organization_id CreateUserlandUserDto: allOf: - type: object properties: email: type: string format: email 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 name: type: - string - 'null' description: The user's full name. example: Marcelina Davis email_verified: type: - boolean - 'null' description: Whether the user's email has been verified. example: true metadata: type: - object - 'null' additionalProperties: *ref_7 maxProperties: 50 example: &ref_12 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 pattern: ^[\x00-\x7F]+$ description: The external ID of the user. example: f1ffa2b2-c20b-4d39-be5c-212726e11222 required: - email - oneOf: - type: object not: anyOf: - properties: password: x-exclude-from-lint: true required: - password - properties: password_hash: x-exclude-from-lint: true required: - password_hash - properties: password_hash_type: x-exclude-from-lint: true required: - password_hash_type - type: object properties: 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! required: - password not: anyOf: - properties: password_hash: x-exclude-from-lint: true required: - password_hash - properties: password_hash_type: x-exclude-from-lint: true required: - password_hash_type - type: object properties: password_hash: type: string description: >- The hashed password to set for the user. Required with `password_hash_type`. Mutually exclusive with `password`. example: $2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy password_hash_type: type: string enum: &ref_13 - bcrypt - firebase-scrypt - ssha - scrypt - pbkdf2 - argon2 description: >- The algorithm originally used to hash the password, used when providing a `password_hash`. Required with `password_hash`. Mutually exclusive with `password`. example: bcrypt required: - password_hash - password_hash_type not: anyOf: - properties: password: x-exclude-from-lint: true required: - password x-mutually-exclusive-body-groups: *ref_11 UpdateUserlandUserDto: allOf: - type: object properties: email: type: string format: email 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 name: type: string description: The user's full name. example: Marcelina Davis email_verified: type: boolean description: Whether the user's email has been verified. example: true metadata: type: - object - 'null' additionalProperties: *ref_7 maxProperties: 50 example: *ref_12 description: >- Object containing metadata key/value pairs associated with the user. propertyNames: maxLength: 40 external_id: type: - string - 'null' maxLength: 128 pattern: ^[\x00-\x7F]+$ 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 - oneOf: - type: object not: anyOf: - properties: password: x-exclude-from-lint: true required: - password - properties: password_hash: x-exclude-from-lint: true required: - password_hash - properties: password_hash_type: x-exclude-from-lint: true required: - password_hash_type - type: object properties: password: type: string description: >- The password to set for the user. Mutually exclusive with `password_hash` and `password_hash_type`. example: strong_password_123! required: - password not: anyOf: - properties: password_hash: x-exclude-from-lint: true required: - password_hash - properties: password_hash_type: x-exclude-from-lint: true required: - password_hash_type - type: object properties: password_hash: type: string description: >- The hashed password to set for the user. Required with `password_hash_type`. Mutually exclusive with `password`. example: $2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy password_hash_type: type: string enum: *ref_13 description: >- The algorithm originally used to hash the password, used when providing a `password_hash`. Required with `password_hash`. Mutually exclusive with `password`. example: bcrypt required: - password_hash - password_hash_type not: anyOf: - properties: password: x-exclude-from-lint: true required: - password x-mutually-exclusive-body-groups: *ref_14 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 format: email 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 SendEmailChangeDto: type: object properties: new_email: type: string description: The new email address to change to. example: new.email@example.com required: - new_email ConfirmEmailChangeDto: type: object properties: code: type: string description: The one-time code used to confirm the email change. example: '123456' required: - code UserlandRevokeSessionDto: type: object properties: session_id: 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 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: type: array description: The events that the Webhook Endpoint is subscribed to. items: type: string enum: &ref_15 - authentication.email_verification_succeeded - authentication.magic_auth_failed - authentication.magic_auth_succeeded - authentication.mfa_succeeded - authentication.oauth_failed - authentication.oauth_succeeded - authentication.password_failed - authentication.password_succeeded - authentication.passkey_failed - authentication.passkey_succeeded - authentication.sso_failed - authentication.sso_started - authentication.sso_succeeded - authentication.sso_timed_out - authentication.radar_risk_detected - api_key.created - api_key.revoked - api_key.updated - connection.activated - connection.deactivated - connection.saml_certificate_renewal_required - connection.saml_certificate_renewed - connection.deleted - dsync.activated - dsync.deleted - dsync.group.created - dsync.group.deleted - dsync.group.updated - dsync.group.user_added - dsync.group.user_removed - dsync.user.created - dsync.user.deleted - dsync.user.updated - email_verification.created - group.created - group.deleted - group.member_added - group.member_removed - group.updated - flag.created - flag.deleted - flag.updated - flag.rule_updated - invitation.accepted - invitation.created - invitation.resent - invitation.revoked - magic_auth.created - organization.created - organization.deleted - organization.updated - organization_domain.created - organization_domain.deleted - organization_domain.updated - organization_domain.verified - organization_domain.verification_failed - password_reset.created - password_reset.succeeded - user.created - user.updated - user.deleted - organization_membership.created - organization_membership.deleted - organization_membership.updated - role.created - role.deleted - role.updated - organization_role.created - organization_role.deleted - organization_role.updated - permission.created - permission.deleted - permission.updated - pipes.connected_account.connected - pipes.connected_account.disconnected - pipes.connected_account.reauthorization_needed - session.created - session.revoked - waitlist_user.approved - waitlist_user.created - waitlist_user.denied example: - user.created - dsync.user.created required: - endpoint_url - events UpdateWebhookEndpointDto: type: object properties: endpoint_url: type: string description: The HTTPS URL where webhooks will be sent. example: https://example.com/webhooks status: type: string enum: - enabled - disabled description: Whether the Webhook Endpoint is enabled or disabled. example: enabled events: type: array description: The events that the Webhook Endpoint is subscribed to. items: type: string enum: *ref_15 example: - user.created - dsync.user.created 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 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 Actor: description: The user or API key that performed an action. properties: id: description: Unique identifier of the actor. example: key_01K8ZYT4AWJ6XP0E0S8CTBHE3P type: string name: description: Display name of the actor. example: My API Key type: string required: - id - name title: Actor type: object CreateDataKeyRequest: properties: context: additionalProperties: maxLength: 500 type: string description: Map of values used to determine the encryption key. example: organization_id: org_01K8ZYT4AWJ6XP0E0S8CTBHE3P maxProperties: 10 type: object required: - context title: CreateDataKeyRequest type: object CreateDataKeyResponse: properties: context: additionalProperties: type: string description: Map of values used to determine the encryption key. example: organization_id: org_01K8ZYT4AWJ6XP0E0S8CTBHE3P type: object data_key: description: Base64-encoded data encryption key. example: DR9idtey9MpMrA1VRFrz30HB1yNgL2PoHZyjAkFeWgg= type: string encrypted_keys: description: Base64-encoded encrypted data key blob. example: >- V09TLkVLTS52MQBiZjUxY2NlYy03OGI0LTUyMDAtYjM4My0zNTczMGU3MWVmNjEBATEBJGJmNjVlMzI2LTQzYTAtNGIyMC04OGM0LTA3ZmYzZGU1NDM0YwF0YmY2NWUzMjYtNDNhMC00YjIwLTg4YzQtMDdmZjNkZTU0MzRj type: string id: description: Unique identifier for the generated data key. example: bf51ccec-78b4-5200-b383-35730e71ef61 type: string required: - id - data_key - encrypted_keys - context title: CreateDataKeyResponse type: object CreateObjectRequest: properties: key_context: additionalProperties: maxLength: 500 type: string description: Map of values used to determine the encryption key. example: organization_id: org_01K8ZYT4AWJ6XP0E0S8CTBHE3P maxProperties: 10 type: object name: description: Unique name for the object. example: my-secret maxLength: 200 type: string value: description: Plaintext data to encrypt and store. example: s3cr3t-v4lu3 type: string required: - name - value - key_context title: CreateObjectRequest type: object DecryptRequest: properties: keys: description: Base64-encoded encrypted data key to decrypt. example: >- V09TLkVLTS52MQBiZjUxY2NlYy03OGI0LTUyMDAtYjM4My0zNTczMGU3MWVmNjEBATEBJGJmNjVlMzI2LTQzYTAtNGIyMC04OGM0LTA3ZmYzZGU1NDM0YwF0YmY2NWUzMjYtNDNhMC00YjIwLTg4YzQtMDdmZjNkZTU0MzRj type: string required: - keys title: DecryptRequest type: object DecryptResponse: properties: data_key: description: Base64-encoded decrypted data key. example: DR9idtey9MpMrA1VRFrz30HB1yNgL2PoHZyjAkFeWgg= type: string id: description: Unique identifier of the decrypted data key. example: bf51ccec-78b4-5200-b383-35730e71ef61 type: string required: - id - data_key title: DecryptResponse type: object DeleteObjectResponse: properties: name: description: Name of the deleted object. example: my-secret type: string success: description: Whether the deletion succeeded. example: true type: boolean required: - success - name title: DeleteObjectResponse type: object Error: description: Error response body. properties: error: description: A human-readable description of the error. example: Invalid request parameters. type: string required: - error title: Error type: object ListMetadata: description: Cursor-based pagination metadata. properties: after: description: Cursor for the next page of results. example: b21f3a8c-7e4d-4b1a-9c5e-2d8f6a7b3c4e type: - string - 'null' before: description: Cursor for the previous page of results. example: a10e2b7d-6c3f-4a2b-8d1e-3f9a5b8c7d6e type: - string - 'null' title: ListMetadata type: object Object: description: An encrypted object with its decrypted value and metadata. properties: id: description: Unique identifier of the object. example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 type: string metadata: $ref: '#/components/schemas/ObjectMetadata' name: description: Unique name of the object. example: my-secret type: string value: description: Decrypted plaintext value. example: s3cr3t-v4lu3 type: string required: - id - name - value - metadata title: Object type: object ObjectListResponse: properties: data: description: List of object summaries. items: $ref: '#/components/schemas/ObjectSummary' type: array list_metadata: $ref: '#/components/schemas/ListMetadata' required: - data - list_metadata title: ObjectListResponse type: object ObjectMetadata: description: Metadata for a stored encrypted object. properties: context: additionalProperties: type: string description: Map of values used to determine the encryption key. example: organization_id: org_01K8ZYT4AWJ6XP0E0S8CTBHE3P type: object environment_id: description: Environment the object belongs to. example: environment_01K8ZYT4AWJ6XP0E0S8CTBHE3P type: string id: description: Unique identifier of the object. example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 type: string key_id: description: Encryption key identifier. example: bf65e326-43a0-4b20-88c4-07ff3de5434c type: string updated_at: description: Timestamp of the last update. example: '2024-06-15T10:30:00Z' format: date-time type: string updated_by: $ref: '#/components/schemas/Actor' version_id: description: Current version identifier of the object. example: c3d4e5f6-7890-abcd-ef12-34567890abcd type: - string - 'null' required: - id - environment_id - key_id - updated_by - updated_at - context title: ObjectMetadata type: object ObjectSummary: description: Summary of an encrypted object returned in list responses. properties: id: description: Unique identifier of the object. example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 type: string name: description: Unique name of the object. example: my-secret type: string updated_at: description: Timestamp of the last update. example: '2024-06-15T10:30:00Z' format: date-time type: - string - 'null' required: - id - name title: ObjectSummary type: object ObjectVersion: description: A static snapshot of an encrypted object. properties: created_at: description: Timestamp when the version was created. example: '2024-06-15T10:30:00Z' format: date-time type: string current_version: description: Whether this is the active version. example: true type: boolean etag: description: Hash of the object value. example: d41d8cd98f00b204e9800998ecf8427e type: string id: description: Unique identifier of the version. example: c3d4e5f6-7890-abcd-ef12-34567890abcd type: string size: description: Number of bytes of stored data. example: 256 type: integer required: - id - created_at - current_version - size - etag title: ObjectVersion type: object ObjectWithoutValue: description: An encrypted object's metadata (value excluded). properties: id: description: Unique identifier of the object. example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 type: string metadata: $ref: '#/components/schemas/ObjectMetadata' name: description: Unique name of the object. example: my-secret type: string required: - id - name - metadata title: ObjectWithoutValue type: object RekeyRequest: properties: context: additionalProperties: maxLength: 500 type: string description: Map of values used to determine the new encryption key. example: organization_id: org_01K8ZYT4AWJ6XP0E0S8CTBHE3P maxProperties: 10 type: object encrypted_keys: description: Base64-encoded encrypted data key blob to re-encrypt. example: >- V09TLkVLTS52MQBiZjUxY2NlYy03OGI0LTUyMDAtYjM4My0zNTczMGU3MWVmNjEBATEBJGJmNjVlMzI2LTQzYTAtNGIyMC04OGM0LTA3ZmYzZGU1NDM0YwF0YmY2NWUzMjYtNDNhMC00YjIwLTg4YzQtMDdmZjNkZTU0MzRj type: string required: - encrypted_keys - context title: RekeyRequest type: object UpdateObjectRequest: properties: value: description: New plaintext value. example: upd4t3d-v4lu3 type: string version_check: description: ID of the expected current version for optimistic locking. example: c3d4e5f6-7890-abcd-ef12-34567890abcd type: - string - 'null' required: - value title: UpdateObjectRequest type: object VersionListResponse: properties: data: description: List of object versions. items: $ref: '#/components/schemas/ObjectVersion' type: array list_metadata: $ref: '#/components/schemas/ListMetadata' required: - data - list_metadata title: VersionListResponse type: object 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: discriminator: propertyName: type oneOf: - 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 - type: object properties: type: type: string description: The type of the API Key owner. example: user const: user id: type: string description: Unique identifier of the API Key owner. example: user_01EHZNVPK3SFK441A1RGBFSHRT organization_id: type: string description: >- Unique identifier of the organization the API Key can access. example: org_01EHZNVPK3SFK441A1RGBFSHRT required: - type - id - organization_id description: The entity that owns the API Key. example: type: organization id: org_01EHZNVPK3SFK441A1RGBFSHRT 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' format: date-time description: Timestamp of when the API Key was last used. example: null expires_at: type: - string - 'null' format: date-time description: >- Timestamp when the API Key expires. Null means the key does not expire. 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 - expires_at - permissions - created_at - updated_at 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: authorized_connect_app_01HXYZ123456789ABCDEFGHIJ granted_scopes: type: array items: type: string description: The scopes granted by the user to the application. example: - openid - profile - email oauth_resource: type: string description: >- The OAuth resource associated with the authorized connect application, if one was requested. example: https://api.example.com/resource 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: authorized_connect_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: authorized_connect_app_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: format: date-time 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: - integer - '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: integer 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 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' description: The schema associated with the action. 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: >- 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 AuthenticationChallengeVerifyResponse: type: object properties: challenge: $ref: '#/components/schemas/AuthenticationChallenge' description: The authentication challenge object. valid: type: boolean description: Whether the code was valid. example: true required: - challenge - valid AuthenticationFactorEnrolled: 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: 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 description: >- TOTP-based authentication factor details. Includes enrollment secrets only available at creation time. 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 AuthenticationFactor: 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: 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 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 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: - object - name - description - organization_id - parent_resource_id - id - external_id - resource_type_slug - created_at - updated_at AuthorizationResourceList: type: object properties: object: type: string description: Indicates this is a list response. const: list data: type: array items: $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: - object - data - list_metadata AuthorizationPermission: type: object properties: object: type: string description: Distinguishes the Permission object. const: permission id: type: string description: Unique identifier of the Permission. example: perm_01HXYZ123456789ABCDEFGHIJ slug: type: string description: >- A unique key to reference the permission. Must be lowercase and contain only letters, numbers, hyphens, underscores, colons, periods, and asterisks. example: documents:read name: type: string description: A descriptive name for the Permission. example: View Documents description: type: - string - 'null' description: An optional description of the Permission. example: Allows viewing document contents system: type: boolean description: >- Whether the permission is a system permission. System permissions are managed by WorkOS and cannot be deleted. example: false resource_type_slug: type: string description: The slug of the resource type associated with the permission. example: workspace created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' updated_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' required: - object - id - slug - name - description - system - resource_type_slug - created_at - updated_at AuthorizationPermissionList: type: object properties: object: type: string description: Indicates this is a list response. const: list data: type: array items: $ref: '#/components/schemas/AuthorizationPermission' description: The list of records for the current page. list_metadata: type: object properties: before: type: - string - 'null' description: >- An object ID that defines your place in the list. When the ID is not present, you are at the start of the list. example: perm_01HXYZ123456789ABCDEFGHIJ after: type: - string - 'null' description: >- An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. example: perm_01HXYZ987654321KJIHGFEDCBA required: - before - after description: Pagination cursors for navigating between pages of results. required: - object - data - list_metadata SlimRole: 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. UserRoleAssignment: 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 organization_membership_id: type: string description: The ID of the organization membership the role is assigned to. example: om_01HXYZ123456789ABCDEFGHIJ role: $ref: '#/components/schemas/SlimRole' 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 the role is assigned on. 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_membership_id - role - resource - created_at - updated_at UserRoleAssignmentList: type: object properties: object: type: string description: Indicates this is a list response. const: list data: type: array items: $ref: '#/components/schemas/UserRoleAssignment' 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 Role: 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 (custom role). example: EnvironmentRole resource_type_slug: type: string description: The slug of the resource type the role is scoped to. example: organization permissions: type: array items: type: string description: The permission slugs assigned to the role. example: - posts:read - posts:write created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' updated_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' required: - slug - object - id - name - description - type - resource_type_slug - permissions - created_at - updated_at RoleList: type: object properties: object: type: string example: list const: list data: type: array items: $ref: '#/components/schemas/Role' description: The list of records for the current page. required: - object - data UserlandUser: 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 name: type: - string - 'null' description: The user's full name. example: Marcelina 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 object. UserlandUserOrganizationMembershipBaseWithUser: 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_01E4ZCR3C56J083X43JQXF3JK5 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' user: $ref: '#/components/schemas/UserlandUser' description: The user that belongs to the organization through this membership. required: - object - id - user_id - organization_id - status - directory_managed - created_at - updated_at - user UserlandUserOrganizationMembershipBaseWithUserList: type: object properties: object: type: string description: Indicates this is a list response. const: list data: type: array items: $ref: >- #/components/schemas/UserlandUserOrganizationMembershipBaseWithUser 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 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: >- 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 ConnectionList: type: object properties: 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: 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: - 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: description: The type of external Directory Provider integrated with. example: gsuite directory type: string enum: - 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 state: description: >- Describes whether the Directory has been successfully connected to an external provider. example: linked type: string enum: - linked - validating - invalid_credentials - unlinked - deleting 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: integer description: Count of active directory users. example: 42 inactive: type: integer description: Count of inactive directory users. example: 3 required: - active - inactive description: Counts of active and inactive directory users. groups: type: integer 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 DirectoryList: type: object properties: object: type: string description: Indicates this is a list response. const: list data: type: array items: $ref: '#/components/schemas/Directory' 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 DirectoryGroup: 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 DirectoryGroupList: type: object properties: object: type: string 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: - object - data - list_metadata - list_metadata DirectoryUserWithGroups: 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 name: type: - string - 'null' description: The full name of the user. example: Marcelina 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. deprecated: true job_title: type: - string - 'null' description: The job title of the user. example: Software Engineer deprecated: true username: type: - string - 'null' description: The username of the user. example: mdavis deprecated: true 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. deprecated: true 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: $ref: '#/components/schemas/SlimRole' 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: $ref: '#/components/schemas/DirectoryGroup' description: >- The directory groups the user belongs to. Deprecated: starting May 1, 2026, this field returns an empty array by default for newly created teams. Existing teams currently depending on this field should migrate to the new access pattern for better throughput performance — the field is unbounded by user, so users with many group memberships produce large, slow response payloads. Use the List Directory Groups endpoint with a `user` filter to fetch a user's group memberships. deprecated: true required: - object - id - directory_id - organization_id - idp_id - email - state - raw_attributes - custom_attributes - created_at - updated_at - groups DirectoryUserList: type: object properties: object: type: string 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: - object - data - list_metadata - list_metadata UserlandUserOrganizationMembershipBaseList: 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_01E4ZCR3C56J083X43JQXF3JK5 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 Group: type: object properties: object: type: string description: The Group object. example: group const: group id: type: string description: The unique ID of the Group. example: group_01HXYZ123456789ABCDEFGHIJ organization_id: type: string description: The ID of the Organization the Group belongs to. example: org_01EHWNCE74X7JSDV0X3SZ3KJNY name: type: string description: The name of the Group. example: Engineering description: type: - string - 'null' description: An optional description of the Group. example: The engineering team 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 - name - description - created_at - updated_at GroupList: type: object properties: object: type: string description: Indicates this is a list response. const: list data: type: array items: $ref: '#/components/schemas/Group' 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: 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: group_01HXYZ987654321KJIHGFEDCBA required: - before - after description: Pagination cursors for navigating between pages of results. required: - object - data - list_metadata EventContextActorDto: type: object properties: id: type: string description: Unique identifier of the actor. example: user_01EHWNCE74X7JSDV0X3SZ3KJNY source: type: string enum: - api - dashboard - admin_portal - system description: The source of the actor that performed the action. name: type: - string - 'null' description: The name of the actor. example: Jane Doe required: - id - source - name description: The actor who performed the action. EventContextDto: type: object properties: google_analytics_client_id: type: string description: The Google Analytics client ID. example: GA1.2.1234567890.1234567890 google_analytics_sessions: type: array items: type: object properties: containerId: type: string description: The Google Analytics container ID. example: GTM-ABCDEF sessionId: type: string description: The Google Analytics session ID. example: '1234567890' sessionNumber: type: string description: The Google Analytics session number. example: '1' required: - containerId description: The Google Analytics sessions associated with the event. ajs_anonymous_id: type: string description: The anonymous ID from analytics. example: ajs_anon_01EHWNCE74X7JSDV0X3SZ3KJNY client_id: type: string description: The client ID associated with the event. example: client_01EHWNCE74X7JSDV0X3SZ3KJNY actor: $ref: '#/components/schemas/EventContextActorDto' previous_attributes: type: object additionalProperties: {} description: Attributes that changed from their previous values. description: Additional context about the event. DirectoryUser: 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 name: type: - string - 'null' description: The full name of the user. example: Marcelina 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. deprecated: true job_title: type: - string - 'null' description: The job title of the user. example: Software Engineer deprecated: true username: type: - string - 'null' description: The username of the user. example: mdavis deprecated: true 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. deprecated: true custom_attributes: type: object additionalProperties: {} description: >- An object containing the custom attribute mapping for the Directory Provider. example: &ref_18 department: Engineering job_title: Software Engineer role: $ref: '#/components/schemas/SlimRole' 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' required: - object - id - directory_id - organization_id - idp_id - email - state - raw_attributes - custom_attributes - created_at - updated_at PipesConnectedAccount: type: object properties: object: type: string description: The connected account object. example: connected_account const: connected_account id: type: string description: The unique ID of the connected account. example: data_installation_01EHZNVPK3SFK441A1RGBFSHRT data_integration_id: type: string description: The unique ID of the data integration. example: data_integration_01EHZNVPK3SFK441A1RGBFSHRT provider_slug: type: string description: The provider slug for this connected account. example: github user_id: type: - string - 'null' description: The ID of the User the connected account belongs to. example: user_01EHZNVPK3SFK441A1RGBFSHRT organization_id: type: - string - 'null' description: The ID of the Organization the connected account belongs to. example: org_01EHWNCE74X7JSDV0X3SZ3KJNY scopes: type: array items: type: string description: The OAuth scopes granted for this connected account. example: - repo - user:email state: type: string enum: - connected - needs_reauthorization description: The state of the connected account. example: connected 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 - data_integration_id - provider_slug - user_id - organization_id - scopes - state - created_at - updated_at VaultByokKeyProvider: type: string enum: - AWS_KMS - GCP_KMS - AZURE_KEY_VAULT example: AWS_KMS description: The external key provider used for BYOK. WaitlistUser: type: object properties: object: type: string description: Distinguishes the Waitlist User object. const: waitlist_user id: type: string description: The unique ID of the Waitlist User. example: wl_user_01E4ZCR3C56J083X43JQXF3JK5 email: type: string description: The email address of the Waitlist User. example: marcelina.davis@example.com state: type: string enum: - pending - approved - denied description: The state of the Waitlist User. example: pending approved_at: format: date-time type: - string - 'null' description: >- The timestamp when the Waitlist User was approved, or null if not yet approved. 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: - object - id - email - state - approved_at - created_at - updated_at EventSchema: allOf: - 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: &ref_16 id: directory_user_01E1JG7J09H96KYP8HM9B0G5SJ directory_id: directory_01ECAZ4NV9QMV47GW873HDCX74 organization_id: org_01EZTR6WYX1A0DSE2CYMGXQ24Y state: active email: veda@foo-corp.com emails: - primary: true type: work value: veda@foo-corp.com idp_id: '2836' object: directory_user username: veda@foo-corp.com last_name: Torp first_name: Veda 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: An event emitted by WorkOS. example: &ref_23 object: event id: event_01EHZNVPK3SFK441A1RGBFSHRT event: dsync.user.created data: *ref_16 created_at: '2021-06-25T19:07:33.155Z' context: {} - oneOf: - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: action.authentication.denied data: type: object properties: action_endpoint_id: type: string description: The ID of the action endpoint. example: action_endpoint_01EHWNCE74X7JSDV0X3SZ3KJNY action_execution_id: type: string description: The ID of the action execution. example: action_execution_01EHWNCE74X7JSDV0X3SZ3KJNY type: type: string description: The type of action that was denied. const: authentication verdict: type: string description: The verdict of the action. const: Deny user_id: type: string description: The ID of the user. example: user_01EHWNCE74X7JSDV0X3SZ3KJNY organization_id: type: - string - 'null' description: The ID of the organization. example: org_01EHWNCE74X7JSDV0X3SZ3KJNY email: type: string description: The email address of the user. example: user@example.com ip_address: type: - string - 'null' description: The IP address of the request. example: 203.0.113.1 user_agent: type: - string - 'null' description: The user agent of the request. example: Mozilla/5.0 required: - action_endpoint_id - action_execution_id - type - verdict - user_id - organization_id - email - ip_address - user_agent description: The event payload. context: $ref: '#/components/schemas/EventContextDto' created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: action.user_registration.denied data: type: object properties: action_endpoint_id: type: string description: The ID of the action endpoint. example: action_endpoint_01EHWNCE74X7JSDV0X3SZ3KJNY action_execution_id: type: string description: The ID of the action execution. example: action_execution_01EHWNCE74X7JSDV0X3SZ3KJNY type: type: string description: The type of action that was denied. const: user_registration verdict: type: string description: The verdict of the action. const: Deny organization_id: type: - string - 'null' description: The ID of the organization. example: org_01EHWNCE74X7JSDV0X3SZ3KJNY email: type: string description: The email address of the user. example: user@example.com ip_address: type: - string - 'null' description: The IP address of the request. example: 203.0.113.1 user_agent: type: - string - 'null' description: The user agent of the request. example: Mozilla/5.0 required: - action_endpoint_id - action_execution_id - type - verdict - organization_id - email - ip_address - user_agent description: The event payload. context: $ref: '#/components/schemas/EventContextDto' created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: api_key.created data: 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_01EHWNCE74X7JSDV0X3SZ3KJNY owner: oneOf: - type: object properties: type: type: string description: The type of the API key owner. const: organization id: type: string description: The unique identifier of the API key owner. example: org_01EHWNCE74X7JSDV0X3SZ3KJNY required: - type - id - type: object properties: type: type: string description: The type of the API key owner. const: user id: type: string description: >- The unique identifier of the user who owns the API key. example: user_01EHWNCE74X7JSDV0X3SZ3KJNY organization_id: type: string description: >- The unique identifier of the organization the API key belongs to. example: org_01EHWNCE74X7JSDV0X3SZ3KJNY required: - type - id - organization_id description: The owner of the API key. name: type: string description: The name of the API key. example: My API Key obfuscated_value: type: string description: The obfuscated value of the API key. example: sk_test_...1234 last_used_at: type: - string - 'null' description: The timestamp when the API key was last used. example: '2026-01-15T12:00:00.000Z' expires_at: type: - string - 'null' format: date-time description: >- Timestamp when the API Key expires. Null means the key does not expire. example: null permissions: type: array items: type: string description: The permissions granted to the API key. example: &ref_17 - users:read - users:write created_at: type: string description: The timestamp when the API key was created. example: '2026-01-15T12:00:00.000Z' updated_at: type: string description: The timestamp when the API key was last updated. example: '2026-01-15T12:00:00.000Z' required: - object - id - owner - name - obfuscated_value - last_used_at - expires_at - permissions - created_at - updated_at description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: api_key.revoked data: 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_01EHWNCE74X7JSDV0X3SZ3KJNY owner: oneOf: - type: object properties: type: type: string description: The type of the API key owner. const: organization id: type: string description: The unique identifier of the API key owner. example: org_01EHWNCE74X7JSDV0X3SZ3KJNY required: - type - id - type: object properties: type: type: string description: The type of the API key owner. const: user id: type: string description: >- The unique identifier of the user who owns the API key. example: user_01EHWNCE74X7JSDV0X3SZ3KJNY organization_id: type: string description: >- The unique identifier of the organization the API key belongs to. example: org_01EHWNCE74X7JSDV0X3SZ3KJNY required: - type - id - organization_id description: The owner of the API key. name: type: string description: The name of the API key. example: My API Key obfuscated_value: type: string description: The obfuscated value of the API key. example: sk_test_...1234 last_used_at: type: - string - 'null' description: The timestamp when the API key was last used. example: '2026-01-15T12:00:00.000Z' expires_at: type: - string - 'null' format: date-time description: >- Timestamp when the API Key expires. Null means the key does not expire. example: null permissions: type: array items: type: string description: The permissions granted to the API key. example: *ref_17 created_at: type: string description: The timestamp when the API key was created. example: '2026-01-15T12:00:00.000Z' updated_at: type: string description: The timestamp when the API key was last updated. example: '2026-01-15T12:00:00.000Z' required: - object - id - owner - name - obfuscated_value - last_used_at - expires_at - permissions - created_at - updated_at description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: api_key.updated data: 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_01EHWNCE74X7JSDV0X3SZ3KJNY owner: oneOf: - type: object properties: type: type: string description: The type of the API key owner. const: organization id: type: string description: The unique identifier of the API key owner. example: org_01EHWNCE74X7JSDV0X3SZ3KJNY required: - type - id - type: object properties: type: type: string description: The type of the API key owner. const: user id: type: string description: >- The unique identifier of the user who owns the API key. example: user_01EHWNCE74X7JSDV0X3SZ3KJNY organization_id: type: string description: >- The unique identifier of the organization the API key belongs to. example: org_01EHWNCE74X7JSDV0X3SZ3KJNY required: - type - id - organization_id description: The owner of the API key. name: type: string description: The name of the API key. example: My API Key obfuscated_value: type: string description: The obfuscated value of the API key. example: sk_test_...1234 last_used_at: type: - string - 'null' description: The timestamp when the API key was last used. example: '2026-01-15T12:00:00.000Z' expires_at: type: - string - 'null' format: date-time description: >- Timestamp when the API Key expires. Null means the key does not expire. example: null permissions: type: array items: type: string description: The permissions granted to the API key. example: *ref_17 created_at: type: string description: The timestamp when the API key was created. example: '2026-01-15T12:00:00.000Z' updated_at: type: string description: The timestamp when the API key was last updated. example: '2026-01-15T12:00:00.000Z' previous_attributes: type: object properties: expires_at: type: - string - 'null' format: date-time description: >- The previous timestamp when the API Key expired. Null means the key did not expire. example: null required: - expires_at description: Previous API key attributes before the update. required: - object - id - owner - name - obfuscated_value - last_used_at - expires_at - permissions - created_at - updated_at - previous_attributes description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: authentication.email_verification_failed data: type: object properties: type: type: string const: email_verification status: type: string const: failed ip_address: type: - string - 'null' description: The IP address of the request. example: 203.0.113.42 user_agent: type: - string - 'null' description: The user agent of the request. example: Mozilla/5.0 user_id: type: - string - 'null' description: The ID of the user. example: user_01E4ZCR3C56J083X43JQXF3JK5 email: type: - string - 'null' description: The email address of the user. example: user@example.com error: type: object properties: code: type: string description: The error code. example: mfa_challenge_failed message: type: string description: A human-readable error message. example: The MFA challenge has failed. required: - code - message description: Details about the authentication error. required: - type - status - ip_address - user_agent - user_id - email - error description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: authentication.email_verification_succeeded data: type: object properties: type: type: string const: email_verification status: type: string const: succeeded ip_address: type: - string - 'null' description: The IP address of the request. example: 203.0.113.42 user_agent: type: - string - 'null' description: The user agent of the request. example: Mozilla/5.0 user_id: type: string description: The ID of the user. example: user_01E4ZCR3C56J083X43JQXF3JK5 email: type: string description: The email address of the user. example: user@example.com required: - type - status - ip_address - user_agent - user_id - email description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: authentication.magic_auth_failed data: type: object properties: type: type: string const: magic_auth status: type: string const: failed ip_address: type: - string - 'null' description: The IP address of the request. example: 203.0.113.42 user_agent: type: - string - 'null' description: The user agent of the request. example: Mozilla/5.0 user_id: type: - string - 'null' description: The ID of the user. example: user_01E4ZCR3C56J083X43JQXF3JK5 email: type: - string - 'null' description: The email address of the user. example: user@example.com error: type: object properties: code: type: string description: The error code. example: mfa_challenge_failed message: type: string description: A human-readable error message. example: The MFA challenge has failed. required: - code - message description: Details about the authentication error. required: - type - status - ip_address - user_agent - user_id - email - error description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: authentication.magic_auth_succeeded data: type: object properties: type: type: string const: magic_auth status: type: string const: succeeded ip_address: type: - string - 'null' description: The IP address of the request. example: 203.0.113.42 user_agent: type: - string - 'null' description: The user agent of the request. example: Mozilla/5.0 user_id: type: string description: The ID of the user. example: user_01E4ZCR3C56J083X43JQXF3JK5 email: type: string description: The email address of the user. example: user@example.com required: - type - status - ip_address - user_agent - user_id - email description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: authentication.mfa_failed data: type: object properties: type: type: string const: mfa status: type: string const: failed ip_address: type: - string - 'null' description: The IP address of the request. example: 203.0.113.42 user_agent: type: - string - 'null' description: The user agent of the request. example: Mozilla/5.0 user_id: type: - string - 'null' description: The ID of the user. example: user_01E4ZCR3C56J083X43JQXF3JK5 email: type: - string - 'null' description: The email address of the user. example: user@example.com error: type: object properties: code: type: string description: The error code. example: mfa_challenge_failed message: type: string description: A human-readable error message. example: The MFA challenge has failed. required: - code - message description: Details about the authentication error. required: - type - status - ip_address - user_agent - user_id - email - error description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: authentication.mfa_succeeded data: type: object properties: type: type: string const: mfa status: type: string const: succeeded ip_address: type: - string - 'null' description: The IP address of the request. example: 203.0.113.42 user_agent: type: - string - 'null' description: The user agent of the request. example: Mozilla/5.0 user_id: type: string description: The ID of the user. example: user_01E4ZCR3C56J083X43JQXF3JK5 email: type: string description: The email address of the user. example: user@example.com required: - type - status - ip_address - user_agent - user_id - email description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: authentication.oauth_failed data: type: object properties: type: type: string const: oauth status: type: string const: failed ip_address: type: - string - 'null' description: The IP address of the request. example: 203.0.113.42 user_agent: type: - string - 'null' description: The user agent of the request. example: Mozilla/5.0 user_id: type: - string - 'null' description: The ID of the user. example: user_01E4ZCR3C56J083X43JQXF3JK5 email: type: - string - 'null' description: The email address of the user. example: user@example.com error: type: object properties: code: type: string description: The error code. example: mfa_challenge_failed message: type: string description: A human-readable error message. example: The MFA challenge has failed. required: - code - message description: Details about the authentication error. required: - type - status - ip_address - user_agent - user_id - email - error description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: authentication.oauth_succeeded data: type: object properties: type: type: string const: oauth status: type: string const: succeeded ip_address: type: - string - 'null' description: The IP address of the request. example: 203.0.113.42 user_agent: type: - string - 'null' description: The user agent of the request. example: Mozilla/5.0 user_id: type: - string - 'null' description: The ID of the user. example: user_01E4ZCR3C56J083X43JQXF3JK5 email: type: string description: The email address of the user. example: user@example.com required: - type - status - ip_address - user_agent - user_id - email description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: authentication.passkey_failed data: type: object properties: type: type: string const: passkey status: type: string const: failed ip_address: type: - string - 'null' description: The IP address of the request. example: 203.0.113.42 user_agent: type: - string - 'null' description: The user agent of the request. example: Mozilla/5.0 user_id: type: - string - 'null' description: The ID of the user. example: user_01E4ZCR3C56J083X43JQXF3JK5 email: type: - string - 'null' description: The email address of the user. example: user@example.com error: type: object properties: code: type: string description: The error code. example: mfa_challenge_failed message: type: string description: A human-readable error message. example: The MFA challenge has failed. required: - code - message description: Details about the authentication error. required: - type - status - ip_address - user_agent - user_id - email - error description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: authentication.passkey_succeeded data: type: object properties: type: type: string const: passkey status: type: string const: succeeded ip_address: type: - string - 'null' description: The IP address of the request. example: 203.0.113.42 user_agent: type: - string - 'null' description: The user agent of the request. example: Mozilla/5.0 user_id: type: string description: The ID of the user. example: user_01E4ZCR3C56J083X43JQXF3JK5 email: type: string description: The email address of the user. example: user@example.com required: - type - status - ip_address - user_agent - user_id - email description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: authentication.password_failed data: type: object properties: type: type: string const: password status: type: string const: failed ip_address: type: - string - 'null' description: The IP address of the request. example: 203.0.113.42 user_agent: type: - string - 'null' description: The user agent of the request. example: Mozilla/5.0 user_id: type: - string - 'null' description: The ID of the user. example: user_01E4ZCR3C56J083X43JQXF3JK5 email: type: - string - 'null' description: The email address of the user. example: user@example.com error: type: object properties: code: type: string description: The error code. example: mfa_challenge_failed message: type: string description: A human-readable error message. example: The MFA challenge has failed. required: - code - message description: Details about the authentication error. required: - type - status - ip_address - user_agent - user_id - email - error description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: authentication.password_succeeded data: type: object properties: type: type: string const: password status: type: string const: succeeded ip_address: type: - string - 'null' description: The IP address of the request. example: 203.0.113.42 user_agent: type: - string - 'null' description: The user agent of the request. example: Mozilla/5.0 user_id: type: string description: The ID of the user. example: user_01E4ZCR3C56J083X43JQXF3JK5 email: type: string description: The email address of the user. example: user@example.com required: - type - status - ip_address - user_agent - user_id - email description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: authentication.radar_risk_detected data: type: object properties: auth_method: type: string description: The authentication method used. example: password action: type: string enum: - signup - login control: type: - string - 'null' description: The control action taken for the detected risk. example: block blocklist_type: type: - string - 'null' description: The type of blocklist that triggered the risk detection. example: ip ip_address: type: - string - 'null' description: The IP address of the request. example: 203.0.113.42 user_agent: type: - string - 'null' description: The user agent of the request. example: Mozilla/5.0 user_id: type: string description: The ID of the user. example: user_01E4ZCR3C56J083X43JQXF3JK5 email: type: string description: The email address of the user. example: user@example.com required: - auth_method - action - control - blocklist_type - ip_address - user_agent - user_id - email description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: authentication.sso_failed data: type: object properties: type: type: string const: sso status: type: string const: failed ip_address: type: - string - 'null' description: The IP address of the request. example: 203.0.113.42 user_agent: type: - string - 'null' description: The user agent of the request. example: Mozilla/5.0 user_id: type: - string - 'null' description: The ID of the user. example: user_01E4ZCR3C56J083X43JQXF3JK5 email: type: - string - 'null' description: The email address of the user. example: user@example.com sso: type: object properties: organization_id: type: - string - 'null' description: The ID of the organization. example: org_01EHWNCE74X7JSDV0X3SZ3KJNY connection_id: type: - string - 'null' description: The ID of the SSO connection. example: conn_01E4ZCR3C56J083X43JQXF3JK5 session_id: type: - string - 'null' description: The ID of the SSO session. example: sess_01E4ZCR3C56J083X43JQXF3JK5 required: - organization_id - connection_id - session_id description: SSO connection details. error: type: object properties: code: type: string description: The error code. example: mfa_challenge_failed message: type: string description: A human-readable error message. example: The MFA challenge has failed. required: - code - message description: Details about the authentication error. required: - type - status - ip_address - user_agent - user_id - email - sso - error description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: authentication.sso_started data: type: object properties: type: type: string const: sso status: type: string const: started ip_address: type: - string - 'null' description: The IP address of the request. example: 203.0.113.42 user_agent: type: - string - 'null' description: The user agent of the request. example: Mozilla/5.0 user_id: type: - string - 'null' description: The ID of the user. example: user_01E4ZCR3C56J083X43JQXF3JK5 email: type: - string - 'null' description: The email address of the user. example: user@example.com sso: type: object properties: organization_id: type: - string - 'null' description: The ID of the organization. example: org_01EHWNCE74X7JSDV0X3SZ3KJNY connection_id: type: - string - 'null' description: The ID of the SSO connection. example: conn_01E4ZCR3C56J083X43JQXF3JK5 session_id: type: - string - 'null' description: The ID of the SSO session. example: sess_01E4ZCR3C56J083X43JQXF3JK5 required: - organization_id - connection_id - session_id description: SSO connection details. required: - type - status - ip_address - user_agent - user_id - email - sso description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: authentication.sso_succeeded data: type: object properties: type: type: string const: sso status: type: string const: succeeded ip_address: type: - string - 'null' description: The IP address of the request. example: 203.0.113.42 user_agent: type: - string - 'null' description: The user agent of the request. example: Mozilla/5.0 user_id: type: - string - 'null' description: The ID of the user. example: user_01E4ZCR3C56J083X43JQXF3JK5 email: type: string description: The email address of the user. example: user@example.com sso: type: object properties: organization_id: type: - string - 'null' description: The ID of the organization. example: org_01EHWNCE74X7JSDV0X3SZ3KJNY connection_id: type: - string - 'null' description: The ID of the SSO connection. example: conn_01E4ZCR3C56J083X43JQXF3JK5 session_id: type: - string - 'null' description: The ID of the SSO session. example: sess_01E4ZCR3C56J083X43JQXF3JK5 required: - organization_id - connection_id - session_id description: SSO connection details. required: - type - status - ip_address - user_agent - user_id - email - sso description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: authentication.sso_timed_out data: type: object properties: type: type: string const: sso status: type: string const: timed_out ip_address: type: - string - 'null' description: The IP address of the request. example: 203.0.113.42 user_agent: type: - string - 'null' description: The user agent of the request. example: Mozilla/5.0 user_id: type: - string - 'null' description: The ID of the user. example: user_01E4ZCR3C56J083X43JQXF3JK5 email: type: - string - 'null' description: The email address of the user. example: user@example.com sso: type: object properties: organization_id: type: - string - 'null' description: The ID of the organization. example: org_01EHWNCE74X7JSDV0X3SZ3KJNY connection_id: type: - string - 'null' description: The ID of the SSO connection. example: conn_01E4ZCR3C56J083X43JQXF3JK5 session_id: type: - string - 'null' description: The ID of the SSO session. example: sess_01E4ZCR3C56J083X43JQXF3JK5 required: - organization_id - connection_id - session_id description: SSO connection details. error: type: object properties: code: type: string description: The error code. example: mfa_challenge_failed message: type: string description: A human-readable error message. example: The MFA challenge has failed. required: - code - message description: Details about the authentication error. required: - type - status - ip_address - user_agent - user_id - email - sso - error description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: connection.activated data: type: object properties: object: type: string description: Distinguishes the connection object. const: connection id: type: string description: Unique identifier of the connection. example: conn_01EHWNCE74X7JSDV0X3SZ3KJNY state: type: string enum: - draft - active - validating - inactive - deleting description: The current state of the connection. example: active name: type: string description: The name of the connection. example: Acme SSO connection_type: type: string enum: - 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 connection. example: OktaSAML organization_id: type: string description: The ID of the organization the connection belongs to. example: org_01EHWNCE74X7JSDV0X3SZ3KJNY 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' external_key: type: string description: The external key of the connection. example: ext_01EHWNCE74X7JSDV0X3SZ3KJNY status: type: string enum: - linked - unlinked description: Deprecated. Use state instead. example: linked domains: type: array items: type: object properties: object: type: string description: Distinguishes the connection domain object. const: connection_domain id: type: string description: Unique identifier of the connection domain. example: conn_domain_01EHWNCE74X7JSDV0X3SZ3KJNY domain: type: string description: The domain value. example: acme.com required: - object - id - domain description: The domains associated with the connection. required: - object - id - state - name - connection_type - created_at - updated_at - external_key - status - domains description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: connection.deactivated data: type: object properties: object: type: string description: Distinguishes the connection object. const: connection id: type: string description: Unique identifier of the connection. example: conn_01EHWNCE74X7JSDV0X3SZ3KJNY state: type: string enum: - draft - active - validating - inactive - deleting description: The current state of the connection. example: active name: type: string description: The name of the connection. example: Acme SSO connection_type: type: string enum: - 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 connection. example: OktaSAML organization_id: type: string description: The ID of the organization the connection belongs to. example: org_01EHWNCE74X7JSDV0X3SZ3KJNY 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' external_key: type: string description: The external key of the connection. example: ext_01EHWNCE74X7JSDV0X3SZ3KJNY status: type: string enum: - linked - unlinked description: Deprecated. Use state instead. example: linked domains: type: array items: type: object properties: object: type: string description: Distinguishes the connection domain object. const: connection_domain id: type: string description: Unique identifier of the connection domain. example: conn_domain_01EHWNCE74X7JSDV0X3SZ3KJNY domain: type: string description: The domain value. example: acme.com required: - object - id - domain description: The domains associated with the connection. required: - object - id - state - name - connection_type - created_at - updated_at - external_key - status - domains description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: connection.deleted data: type: object properties: object: type: string description: Distinguishes the connection object. const: connection id: type: string description: Unique identifier of the connection. example: conn_01EHWNCE74X7JSDV0X3SZ3KJNY state: type: string enum: - draft - active - validating - inactive - deleting description: The current state of the connection. example: active name: type: string description: The name of the connection. example: Acme SSO connection_type: type: string enum: - 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 connection. example: OktaSAML organization_id: type: string description: The ID of the organization the connection belongs to. example: org_01EHWNCE74X7JSDV0X3SZ3KJNY 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 - name - connection_type - created_at - updated_at description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: connection.saml_certificate_renewal_required data: type: object properties: connection: type: object properties: id: type: string description: Unique identifier of the connection. example: conn_01EHWNCE74X7JSDV0X3SZ3KJNY organization_id: type: string description: >- The ID of the organization the connection belongs to. example: org_01EHWNCE74X7JSDV0X3SZ3KJNY required: - id description: The connection with the expiring certificate. certificate: type: object properties: certificate_type: type: string enum: - ResponseSigning - RequestSigning - ResponseEncryption description: The type of the SAML certificate. example: ResponseSigning expiry_date: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' is_expired: type: boolean description: Whether the certificate has already expired. example: false required: - certificate_type - expiry_date - is_expired description: The SAML certificate details. days_until_expiry: type: integer description: The number of days until the certificate expires. example: 30 required: - connection - certificate - days_until_expiry description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: connection.saml_certificate_renewed data: type: object properties: connection: type: object properties: id: type: string description: Unique identifier of the connection. example: conn_01EHWNCE74X7JSDV0X3SZ3KJNY organization_id: type: string description: >- The ID of the organization the connection belongs to. example: org_01EHWNCE74X7JSDV0X3SZ3KJNY required: - id description: The connection with the renewed certificate. certificate: type: object properties: certificate_type: type: string enum: - ResponseSigning - RequestSigning - ResponseEncryption description: The type of the SAML certificate. example: ResponseSigning expiry_date: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' required: - certificate_type - expiry_date description: The renewed SAML certificate details. renewed_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' required: - connection - certificate - renewed_at description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: dsync.activated data: type: object properties: object: type: string description: Distinguishes the directory object. const: directory id: type: string description: Unique identifier of the directory. example: directory_01EHWNCE74X7JSDV0X3SZ3KJNY organization_id: type: string description: The ID of the organization the directory belongs to. example: org_01EHWNCE74X7JSDV0X3SZ3KJNY type: type: string enum: - azure scim v2.0 - bamboohr - breathe hr - cezanne hr - cyberark scim v2.0 - fourth hr - generic scim v2.0 - gsuite directory - gusto - hibob - jump cloud scim v2.0 - okta scim v2.0 - onelogin scim v2.0 - people hr - personio - pingfederate scim v2.0 - rippling scim v2.0 - rippling - sailpoint scim v2.0 - s3 - sftp - sftp workday - workday description: The type of the directory. example: okta scim v2.0 state: type: string enum: - active - validating - invalid_credentials - inactive - deleting description: The current state of the directory. example: active name: type: string description: The name of the directory. example: Acme Directory 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' external_key: type: string description: The external key of the directory. example: ext_01EHWNCE74X7JSDV0X3SZ3KJNY 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_01EHWNCE74X7JSDV0X3SZ3KJNY domain: type: string description: The domain value. example: acme.com required: - object - id - domain description: The domains associated with the directory. required: - object - id - type - state - name - created_at - updated_at - external_key - domains description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: dsync.deleted data: type: object properties: object: type: string description: Distinguishes the directory object. const: directory id: type: string description: Unique identifier of the directory. example: directory_01EHWNCE74X7JSDV0X3SZ3KJNY organization_id: type: string description: The ID of the organization the directory belongs to. example: org_01EHWNCE74X7JSDV0X3SZ3KJNY type: type: string enum: - azure scim v2.0 - bamboohr - breathe hr - cezanne hr - cyberark scim v2.0 - fourth hr - generic scim v2.0 - gsuite directory - gusto - hibob - jump cloud scim v2.0 - okta scim v2.0 - onelogin scim v2.0 - people hr - personio - pingfederate scim v2.0 - rippling scim v2.0 - rippling - sailpoint scim v2.0 - s3 - sftp - sftp workday - workday description: The type of the directory. example: okta scim v2.0 state: type: string enum: - active - validating - invalid_credentials - inactive - deleting description: The current state of the directory. example: active name: type: string description: The name of the directory. example: Acme Directory 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 - state - name - created_at - updated_at description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: dsync.group.created data: $ref: '#/components/schemas/DirectoryGroup' description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: dsync.group.deleted data: $ref: '#/components/schemas/DirectoryGroup' description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: dsync.group.updated data: 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' previous_attributes: type: object additionalProperties: {} required: - object - id - idp_id - directory_id - organization_id - name - created_at - updated_at description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: dsync.token.created data: type: object properties: object: type: string description: Distinguishes the directory token object. const: directory_token id: type: string description: Unique identifier of the directory token. example: directory_token_01EHWNCE74X7JSDV0X3SZ3KJNY directory_id: type: string description: The ID of the directory the token authenticates to. example: directory_01EHWNCE74X7JSDV0X3SZ3KJNY organization_id: type: string description: The ID of the organization the directory belongs to. example: org_01EHWNCE74X7JSDV0X3SZ3KJNY token_suffix: type: string description: >- The trailing characters of the bearer token, for identification only. The full token value is never included in events. example: a1b2 created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' required: - object - id - directory_id - token_suffix - created_at description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: dsync.token.revoked data: type: object properties: object: type: string description: Distinguishes the directory token object. const: directory_token id: type: string description: Unique identifier of the directory token. example: directory_token_01EHWNCE74X7JSDV0X3SZ3KJNY directory_id: type: string description: The ID of the directory the token authenticates to. example: directory_01EHWNCE74X7JSDV0X3SZ3KJNY organization_id: type: string description: The ID of the organization the directory belongs to. example: org_01EHWNCE74X7JSDV0X3SZ3KJNY token_suffix: type: string description: >- The trailing characters of the bearer token, for identification only. The full token value is never included in events. example: a1b2 created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' required: - object - id - directory_id - token_suffix - created_at description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: dsync.group.user_added data: type: object properties: directory_id: type: string description: The ID of the directory. example: directory_01EHWNCE74X7JSDV0X3SZ3KJNY user: $ref: '#/components/schemas/DirectoryUser' description: The directory user added to the group. group: $ref: '#/components/schemas/DirectoryGroup' description: The directory group the user was added to. required: - directory_id - user - group description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: dsync.user.created data: $ref: '#/components/schemas/DirectoryUser' description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: dsync.user.deleted data: $ref: '#/components/schemas/DirectoryUser' description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: dsync.group.user_removed data: type: object properties: directory_id: type: string description: The ID of the directory. example: directory_01EHWNCE74X7JSDV0X3SZ3KJNY user: $ref: '#/components/schemas/DirectoryUser' description: The directory user removed from the group. group: $ref: '#/components/schemas/DirectoryGroup' description: The directory group the user was removed from. required: - directory_id - user - group description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: dsync.user.updated data: 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 name: type: - string - 'null' description: The full name of the user. example: Marcelina 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. deprecated: true job_title: type: - string - 'null' description: The job title of the user. example: Software Engineer deprecated: true username: type: - string - 'null' description: The username of the user. example: mdavis deprecated: true 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. deprecated: true custom_attributes: type: object additionalProperties: {} description: >- An object containing the custom attribute mapping for the Directory Provider. example: *ref_18 role: $ref: '#/components/schemas/SlimRole' 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' previous_attributes: type: object additionalProperties: {} required: - object - id - directory_id - organization_id - idp_id - email - state - raw_attributes - custom_attributes - created_at - updated_at description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: email_verification.created data: 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' required: - object - id - user_id - email - expires_at - created_at - updated_at description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: flag.created data: type: object properties: object: type: string const: feature_flag id: type: string description: Unique identifier of the Feature Flag. example: flag_01EHZNVPK3SFK441A1RGBFSHRT environment_id: type: string description: The ID of the environment the Feature Flag belongs to. example: environment_01EHWNCE74X7JSDV0X3SZ3KJNY 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. 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: &ref_19 - 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 - environment_id - slug - name - description - owner - tags - enabled - default_value - created_at - updated_at description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: type: object properties: client_id: type: string description: The client ID associated with the flag event. example: client_01EHWNCE74X7JSDV0X3SZ3KJNY actor: type: object properties: id: type: string description: Unique identifier of the actor. example: user_01EHWNCE74X7JSDV0X3SZ3KJNY source: type: string enum: - api - dashboard - admin_portal - system description: The source of the actor that performed the action. name: type: - string - 'null' description: The name of the actor. example: Jane Doe required: - id - source - name description: The actor who performed the action. required: - client_id - actor description: Additional context about the event. object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - context - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: flag.deleted data: type: object properties: object: type: string const: feature_flag id: type: string description: Unique identifier of the Feature Flag. example: flag_01EHZNVPK3SFK441A1RGBFSHRT environment_id: type: string description: The ID of the environment the Feature Flag belongs to. example: environment_01EHWNCE74X7JSDV0X3SZ3KJNY 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. 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: *ref_19 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 - environment_id - slug - name - description - owner - tags - enabled - default_value - created_at - updated_at description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: type: object properties: client_id: type: string description: The client ID associated with the flag event. example: client_01EHWNCE74X7JSDV0X3SZ3KJNY actor: type: object properties: id: type: string description: Unique identifier of the actor. example: user_01EHWNCE74X7JSDV0X3SZ3KJNY source: type: string enum: - api - dashboard - admin_portal - system description: The source of the actor that performed the action. name: type: - string - 'null' description: The name of the actor. example: Jane Doe required: - id - source - name description: The actor who performed the action. required: - client_id - actor description: Additional context about the event. object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - context - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: flag.rule_updated data: type: object properties: object: type: string const: feature_flag id: type: string description: Unique identifier of the Feature Flag. example: flag_01EHZNVPK3SFK441A1RGBFSHRT environment_id: type: string description: The ID of the environment the Feature Flag belongs to. example: environment_01EHWNCE74X7JSDV0X3SZ3KJNY 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. 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: *ref_19 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 - environment_id - slug - name - description - owner - tags - enabled - default_value - created_at - updated_at description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: type: object properties: client_id: type: string description: The client ID associated with the flag event. example: client_01EHWNCE74X7JSDV0X3SZ3KJNY actor: type: object properties: id: type: string description: Unique identifier of the actor. example: user_01EHWNCE74X7JSDV0X3SZ3KJNY source: type: string enum: - api - dashboard - admin_portal - system name: type: - string - 'null' description: The name of the actor. example: Jane Doe required: - id - source - name description: The actor who performed the action. access_type: type: string enum: - none - some - all description: The access type of the flag rule. configured_targets: type: object properties: organizations: type: array items: type: object properties: id: type: string description: The ID of the organization. example: org_01EHWNCE74X7JSDV0X3SZ3KJNY name: type: string description: The name of the organization. example: Acme Corp required: - id - name description: The organizations targeted by the flag rule. users: type: array items: type: object properties: id: type: string description: The ID of the user. example: user_01EHWNCE74X7JSDV0X3SZ3KJNY email: type: string description: The email of the user. example: user@example.com required: - id - email description: The users targeted by the flag rule. required: - organizations - users description: The configured targets for the flag rule. previous_attributes: type: object properties: data: type: object properties: enabled: type: boolean description: Whether the flag was previously enabled. example: true default_value: type: boolean description: The previous default value of the flag. example: false description: The previous data attributes of the flag. context: type: object properties: access_type: type: string enum: - none - some - all description: The previous access type of the flag rule. configured_targets: type: object properties: organizations: type: array items: type: object properties: id: type: string description: The ID of the organization. example: org_01EHWNCE74X7JSDV0X3SZ3KJNY name: type: string description: The name of the organization. example: Acme Corp required: - id - name description: The organizations targeted by the flag rule. users: type: array items: type: object properties: id: type: string description: The ID of the user. example: user_01EHWNCE74X7JSDV0X3SZ3KJNY email: type: string description: The email of the user. example: user@example.com required: - id - email description: The users targeted by the flag rule. required: - organizations - users description: >- The previous configured targets for the flag rule. description: The previous context attributes of the flag rule. description: Attributes that changed from their previous values. required: - client_id - actor - access_type - configured_targets - previous_attributes description: Additional context about the event. object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - context - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: flag.updated data: type: object properties: object: type: string const: feature_flag id: type: string description: Unique identifier of the Feature Flag. example: flag_01EHZNVPK3SFK441A1RGBFSHRT environment_id: type: string description: The ID of the environment the Feature Flag belongs to. example: environment_01EHWNCE74X7JSDV0X3SZ3KJNY 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. 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: *ref_19 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 - environment_id - slug - name - description - owner - tags - enabled - default_value - created_at - updated_at description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: type: object properties: client_id: type: string description: The client ID associated with the flag event. example: client_01EHWNCE74X7JSDV0X3SZ3KJNY actor: type: object properties: id: type: string description: Unique identifier of the actor. example: user_01EHWNCE74X7JSDV0X3SZ3KJNY source: type: string enum: - api - dashboard - admin_portal - system description: The source of the actor that performed the action. name: type: - string - 'null' description: The name of the actor. example: Jane Doe required: - id - source - name description: The actor who performed the action. previous_attributes: type: object properties: data: type: object properties: name: type: string description: The previous name of the flag. example: My Feature Flag description: type: - string - 'null' description: The previous description of the flag. example: Enables the new feature. tags: type: array items: type: string description: The previous tags of the flag. example: - beta - release enabled: type: boolean description: Whether the flag was previously enabled. example: true default_value: type: boolean description: The previous default value of the flag. example: false description: The previous data attributes of the flag. description: Attributes that changed from their previous values. required: - client_id - actor description: Additional context about the event. object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - context - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: group.created data: $ref: '#/components/schemas/Group' description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: group.deleted data: $ref: '#/components/schemas/Group' description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: group.member_added data: type: object properties: group_id: type: string description: The ID of the Group. example: group_01HXYZ123456789ABCDEFGHIJ organization_membership_id: type: string description: The ID of the OrganizationMembership. example: om_01EHWNCE74X7JSDV0X3SZ3KJNY required: - group_id - organization_membership_id description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: group.member_removed data: type: object properties: group_id: type: string description: The ID of the Group. example: group_01HXYZ123456789ABCDEFGHIJ organization_membership_id: type: string description: The ID of the OrganizationMembership. example: om_01EHWNCE74X7JSDV0X3SZ3KJNY required: - group_id - organization_membership_id description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: group.updated data: $ref: '#/components/schemas/Group' description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: invitation.accepted data: 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_01HYGBX8ZGD19949T3BM4FW1C3 accepted_user_id: type: - string - 'null' description: >- The ID of the user who accepted the invitation, once accepted. example: null role_slug: type: - string - 'null' description: >- Slug of the role the invitee will be assigned on acceptance. Reflects the current role on the invitee's organization membership. null when the invitation has no associated organization. example: admin 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 - email - state - accepted_at - revoked_at - expires_at - organization_id - inviter_user_id - accepted_user_id - role_slug - created_at - updated_at description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: invitation.created data: 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_01HYGBX8ZGD19949T3BM4FW1C3 accepted_user_id: type: - string - 'null' description: >- The ID of the user who accepted the invitation, once accepted. example: null role_slug: type: - string - 'null' description: >- Slug of the role the invitee will be assigned on acceptance. Reflects the current role on the invitee's organization membership. null when the invitation has no associated organization. example: admin 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 - email - state - accepted_at - revoked_at - expires_at - organization_id - inviter_user_id - accepted_user_id - role_slug - created_at - updated_at description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: invitation.resent data: 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_01HYGBX8ZGD19949T3BM4FW1C3 accepted_user_id: type: - string - 'null' description: >- The ID of the user who accepted the invitation, once accepted. example: null role_slug: type: - string - 'null' description: >- Slug of the role the invitee will be assigned on acceptance. Reflects the current role on the invitee's organization membership. null when the invitation has no associated organization. example: admin 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 - email - state - accepted_at - revoked_at - expires_at - organization_id - inviter_user_id - accepted_user_id - role_slug - created_at - updated_at description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: invitation.revoked data: 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_01HYGBX8ZGD19949T3BM4FW1C3 accepted_user_id: type: - string - 'null' description: >- The ID of the user who accepted the invitation, once accepted. example: null role_slug: type: - string - 'null' description: >- Slug of the role the invitee will be assigned on acceptance. Reflects the current role on the invitee's organization membership. null when the invitation has no associated organization. example: admin 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 - email - state - accepted_at - revoked_at - expires_at - organization_id - inviter_user_id - accepted_user_id - role_slug - created_at - updated_at description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: magic_auth.created data: 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' required: - object - id - user_id - email - expires_at - created_at - updated_at description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: organization.created data: 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: &ref_20 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' required: - object - id - name - domains - metadata - external_id - created_at - updated_at description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: organization.deleted data: 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: *ref_20 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' required: - object - id - name - domains - metadata - external_id - created_at - updated_at description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: organization_domain.created data: 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: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: organization_domain.deleted data: 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: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: organization_domain.updated data: 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: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: organization_domain.verification_failed data: type: object properties: reason: type: string enum: - domain_verification_period_expired - domain_verified_by_other_organization description: The reason the domain verification failed. example: domain_verification_period_expired organization_domain: 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: The organization domain that failed verification. required: - reason - organization_domain description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: organization_domain.verified data: 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: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: organization_membership.created data: type: object properties: object: type: string description: Distinguishes the organization membership object. const: organization_membership id: type: string description: Unique identifier of the organization membership. example: om_01EHWNCE74X7JSDV0X3SZ3KJNY user_id: type: string description: The ID of the user. example: user_01EHWNCE74X7JSDV0X3SZ3KJNY organization_id: type: string description: The ID of the organization. example: org_01EHWNCE74X7JSDV0X3SZ3KJNY status: type: string enum: - active - inactive - pending description: The status of the organization membership. example: active role: $ref: '#/components/schemas/SlimRole' description: The role associated with the membership. roles: type: array items: $ref: '#/components/schemas/SlimRole' description: The roles associated with the membership. custom_attributes: type: object additionalProperties: {} description: Custom attributes associated with the membership. directory_managed: type: boolean description: >- Whether the membership is managed by a directory sync provider. 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 - user_id - organization_id - status - role - custom_attributes - directory_managed - created_at - updated_at description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: organization_membership.deleted data: type: object properties: object: type: string description: Distinguishes the organization membership object. const: organization_membership id: type: string description: Unique identifier of the organization membership. example: om_01EHWNCE74X7JSDV0X3SZ3KJNY user_id: type: string description: The ID of the user. example: user_01EHWNCE74X7JSDV0X3SZ3KJNY organization_id: type: string description: The ID of the organization. example: org_01EHWNCE74X7JSDV0X3SZ3KJNY status: type: string enum: - active - inactive - pending description: The status of the organization membership. example: active role: $ref: '#/components/schemas/SlimRole' description: The role associated with the membership. roles: type: array items: $ref: '#/components/schemas/SlimRole' description: The roles associated with the membership. custom_attributes: type: object additionalProperties: {} description: Custom attributes associated with the membership. directory_managed: type: boolean description: >- Whether the membership is managed by a directory sync provider. 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 - user_id - organization_id - status - role - custom_attributes - directory_managed - created_at - updated_at description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: organization_membership.updated data: type: object properties: object: type: string description: Distinguishes the organization membership object. const: organization_membership id: type: string description: Unique identifier of the organization membership. example: om_01EHWNCE74X7JSDV0X3SZ3KJNY user_id: type: string description: The ID of the user. example: user_01EHWNCE74X7JSDV0X3SZ3KJNY organization_id: type: string description: The ID of the organization. example: org_01EHWNCE74X7JSDV0X3SZ3KJNY status: type: string enum: - active - inactive - pending description: The status of the organization membership. example: active role: $ref: '#/components/schemas/SlimRole' description: The role associated with the membership. roles: type: array items: $ref: '#/components/schemas/SlimRole' description: The roles associated with the membership. custom_attributes: type: object additionalProperties: {} description: Custom attributes associated with the membership. directory_managed: type: boolean description: >- Whether the membership is managed by a directory sync provider. 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 - user_id - organization_id - status - role - custom_attributes - directory_managed - created_at - updated_at description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: organization_role.created data: type: object properties: object: type: string description: Distinguishes the organization role object. const: organization_role organization_id: type: string description: The ID of the organization the role belongs to. example: org_01EHWNCE74X7JSDV0X3SZ3KJNY slug: type: string description: The slug identifier of the role. example: billing-admin name: type: string description: The name of the role. example: Billing Administrator description: type: - string - 'null' description: A description of the role. example: Can manage billing settings. resource_type_slug: type: string description: The slug of the resource type the role applies to. example: organization permissions: type: array items: type: string description: The permissions granted by the role. example: &ref_21 - users:read - users: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 - organization_id - slug - name - description - resource_type_slug - permissions - created_at - updated_at description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: organization_role.deleted data: type: object properties: object: type: string description: Distinguishes the organization role object. const: organization_role organization_id: type: string description: The ID of the organization the role belongs to. example: org_01EHWNCE74X7JSDV0X3SZ3KJNY slug: type: string description: The slug identifier of the role. example: billing-admin name: type: string description: The name of the role. example: Billing Administrator description: type: - string - 'null' description: A description of the role. example: Can manage billing settings. resource_type_slug: type: string description: The slug of the resource type the role applies to. example: organization permissions: type: array items: type: string description: The permissions granted by the role. example: *ref_21 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 - organization_id - slug - name - description - resource_type_slug - permissions - created_at - updated_at description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: organization_role.updated data: type: object properties: object: type: string description: Distinguishes the organization role object. const: organization_role organization_id: type: string description: The ID of the organization the role belongs to. example: org_01EHWNCE74X7JSDV0X3SZ3KJNY slug: type: string description: The slug identifier of the role. example: billing-admin name: type: string description: The name of the role. example: Billing Administrator description: type: - string - 'null' description: A description of the role. example: Can manage billing settings. resource_type_slug: type: string description: The slug of the resource type the role applies to. example: organization permissions: type: array items: type: string description: The permissions granted by the role. example: *ref_21 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 - organization_id - slug - name - description - resource_type_slug - permissions - created_at - updated_at description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: organization.updated data: 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: *ref_20 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' required: - object - id - name - domains - metadata - external_id - created_at - updated_at description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: password_reset.created data: 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' required: - object - id - user_id - email - expires_at - created_at description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: password_reset.succeeded data: 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' required: - object - id - user_id - email - expires_at - created_at description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: permission.created data: type: object properties: object: type: string description: Distinguishes the permission object. const: permission id: type: string description: Unique identifier of the permission. example: perm_01EHWNCE74X7JSDV0X3SZ3KJNY slug: type: string description: The slug identifier of the permission. example: billing:manage name: type: string description: The name of the permission. example: Manage Billing description: type: - string - 'null' description: A description of the permission. example: Allows managing billing settings. system: type: boolean description: Whether the permission is a system permission. 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 - system - created_at - updated_at description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: permission.deleted data: type: object properties: object: type: string description: Distinguishes the permission object. const: permission id: type: string description: Unique identifier of the permission. example: perm_01EHWNCE74X7JSDV0X3SZ3KJNY slug: type: string description: The slug identifier of the permission. example: billing:manage name: type: string description: The name of the permission. example: Manage Billing description: type: - string - 'null' description: A description of the permission. example: Allows managing billing settings. system: type: boolean description: Whether the permission is a system permission. 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 - system - created_at - updated_at description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: permission.updated data: type: object properties: object: type: string description: Distinguishes the permission object. const: permission id: type: string description: Unique identifier of the permission. example: perm_01EHWNCE74X7JSDV0X3SZ3KJNY slug: type: string description: The slug identifier of the permission. example: billing:manage name: type: string description: The name of the permission. example: Manage Billing description: type: - string - 'null' description: A description of the permission. example: Allows managing billing settings. system: type: boolean description: Whether the permission is a system permission. 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 - system - created_at - updated_at description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: pipes.connected_account.connected data: $ref: '#/components/schemas/PipesConnectedAccount' description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: pipes.connected_account.disconnected data: $ref: '#/components/schemas/PipesConnectedAccount' description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: pipes.connected_account.reauthorization_needed data: $ref: '#/components/schemas/PipesConnectedAccount' description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: role.created data: type: object properties: object: type: string description: Distinguishes the role object. const: role slug: type: string description: The slug identifier of the role. example: admin resource_type_slug: type: string description: The slug of the resource type the role applies to. example: organization permissions: type: array items: type: string description: The permissions granted by the role. example: &ref_22 - users:read - users: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 - slug - resource_type_slug - created_at - updated_at description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: role.deleted data: type: object properties: object: type: string description: Distinguishes the role object. const: role slug: type: string description: The slug identifier of the role. example: admin resource_type_slug: type: string description: The slug of the resource type the role applies to. example: organization permissions: type: array items: type: string description: The permissions granted by the role. example: *ref_22 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 - slug - resource_type_slug - created_at - updated_at description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: role.updated data: type: object properties: object: type: string description: Distinguishes the role object. const: role slug: type: string description: The slug identifier of the role. example: admin resource_type_slug: type: string description: The slug of the resource type the role applies to. example: organization permissions: type: array items: type: string description: The permissions granted by the role. example: *ref_22 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 - slug - resource_type_slug - created_at - updated_at description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: session.created data: type: object properties: object: type: string 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: >- 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: - object - id - ip_address - user_agent - user_id - auth_method - status - expires_at - ended_at - created_at - updated_at description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: session.revoked data: type: object properties: object: type: string 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: >- 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: - object - id - ip_address - user_agent - user_id - auth_method - status - expires_at - ended_at - created_at - updated_at description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: user.created data: $ref: '#/components/schemas/UserlandUser' description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: user.deleted data: $ref: '#/components/schemas/UserlandUser' description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: user.updated data: $ref: '#/components/schemas/UserlandUser' description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: vault.byok_key.deleted data: type: object properties: organization_id: type: string description: The unique identifier of the organization. example: org_01EHT88Z8J8795GZNQ4ZP1J81T key_provider: $ref: '#/components/schemas/VaultByokKeyProvider' required: - organization_id - key_provider description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: vault.byok_key.verification_completed data: type: object properties: organization_id: type: string description: The unique identifier of the organization. example: org_01EHT88Z8J8795GZNQ4ZP1J81T key_provider: $ref: '#/components/schemas/VaultByokKeyProvider' verified: type: boolean description: >- Whether the BYOK key verification completed successfully. example: true required: - organization_id - key_provider - verified description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: vault.data.created data: type: object properties: actor_id: type: string description: The unique identifier of the actor. example: user_01EHWNCE74X7JSDV0X3SZ3KJNY actor_source: type: string enum: - api - dashboard actor_name: type: string description: The name of the actor. example: Jane Doe kv_name: type: string description: The name of the key-value store. example: user-secrets key_id: type: string description: The unique identifier of the encryption key. example: key_01EHWNCE74X7JSDV0X3SZ3KJNY key_context: type: object additionalProperties: type: string required: - actor_id - actor_source - actor_name - kv_name - key_id - key_context description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: vault.data.deleted data: type: object properties: actor_id: type: string description: The unique identifier of the actor. example: user_01EHWNCE74X7JSDV0X3SZ3KJNY actor_source: type: string enum: - api - dashboard actor_name: type: string description: The name of the actor. example: Jane Doe kv_name: type: string description: The name of the key-value store. example: user-secrets required: - actor_id - actor_source - actor_name - kv_name description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: vault.data.read data: type: object properties: actor_id: type: string description: The unique identifier of the actor. example: user_01EHWNCE74X7JSDV0X3SZ3KJNY actor_source: type: string enum: - api - dashboard actor_name: type: string description: The name of the actor. example: Jane Doe kv_name: type: string description: The name of the key-value store. example: user-secrets key_id: type: string description: The unique identifier of the encryption key. example: key_01EHWNCE74X7JSDV0X3SZ3KJNY required: - actor_id - actor_source - actor_name - kv_name - key_id description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: vault.data.updated data: type: object properties: actor_id: type: string description: The unique identifier of the actor. example: user_01EHWNCE74X7JSDV0X3SZ3KJNY actor_source: type: string enum: - api - dashboard actor_name: type: string description: The name of the actor. example: Jane Doe kv_name: type: string description: The name of the key-value store. example: user-secrets key_id: type: string description: The unique identifier of the encryption key. example: key_01EHWNCE74X7JSDV0X3SZ3KJNY key_context: type: object additionalProperties: type: string required: - actor_id - actor_source - actor_name - kv_name - key_id - key_context description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: vault.dek.decrypted data: type: object properties: actor_id: type: string description: The unique identifier of the actor. example: user_01EHWNCE74X7JSDV0X3SZ3KJNY actor_source: type: string enum: - api - dashboard actor_name: type: string description: The name of the actor. example: Jane Doe key_id: type: string description: The unique identifier of the data encryption key. example: key_01EHWNCE74X7JSDV0X3SZ3KJNY required: - actor_id - actor_source - actor_name - key_id description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: vault.dek.read data: type: object properties: actor_id: type: string description: The unique identifier of the actor. example: user_01EHWNCE74X7JSDV0X3SZ3KJNY actor_source: type: string enum: - api - dashboard actor_name: type: string description: The name of the actor. example: Jane Doe key_ids: type: array items: type: string description: The unique identifiers of the data encryption keys. example: - dek_01EHWNCE74X7JSDV0X3SZ3KJNY key_context: type: object additionalProperties: type: string required: - actor_id - actor_source - actor_name - key_ids - key_context description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: vault.kek.created data: type: object properties: actor_id: type: string description: The unique identifier of the actor. example: user_01EHWNCE74X7JSDV0X3SZ3KJNY actor_source: type: string enum: - api - dashboard actor_name: type: string description: The name of the actor. example: Jane Doe key_name: type: string description: The name of the key encryption key. example: production-kek key_id: type: string description: The unique identifier of the key encryption key. example: key_01EHWNCE74X7JSDV0X3SZ3KJNY required: - actor_id - actor_source - actor_name - key_name - key_id description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: vault.metadata.read data: type: object properties: actor_id: type: string description: The unique identifier of the actor. example: user_01EHWNCE74X7JSDV0X3SZ3KJNY actor_source: type: string enum: - api - dashboard actor_name: type: string description: The name of the actor. example: Jane Doe kv_name: type: string description: The name of the key-value store. example: user-secrets required: - actor_id - actor_source - actor_name - kv_name description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: vault.names.listed data: type: object properties: actor_id: type: string description: The unique identifier of the actor. example: user_01EHWNCE74X7JSDV0X3SZ3KJNY actor_source: type: string enum: - api - dashboard actor_name: type: string description: The name of the actor. example: Jane Doe required: - actor_id - actor_source - actor_name description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: waitlist_user.approved data: $ref: '#/components/schemas/WaitlistUser' description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: waitlist_user.created data: $ref: '#/components/schemas/WaitlistUser' description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object - type: object properties: id: type: string description: Unique identifier for the event. example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string const: waitlist_user.denied data: $ref: '#/components/schemas/WaitlistUser' description: The event payload. created_at: format: date-time type: string description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' context: $ref: '#/components/schemas/EventContextDto' object: type: string description: Distinguishes the Event object. const: event required: - id - event - data - created_at - object example: *ref_23 description: An event emitted by WorkOS. EventList: type: object properties: object: type: string description: Indicates this is a list response. const: list data: type: array items: $ref: '#/components/schemas/EventSchema' 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 example: object: list data: - *ref_23 list_metadata: after: event_01EHZNVPK3SFK441A1RGBFSHRT JwtTemplate: 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: >- {"urn:myapp:full_name": "{{user.first_name}} {{user.last_name}}", "urn:myapp:email": "{{user.email}}"} 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 OrganizationDomainStandAlone: 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 Flag: 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 FlagList: type: object properties: object: type: string 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: - object - data - list_metadata OrganizationApiKey: 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' format: date-time description: Timestamp of when the API Key was last used. example: null expires_at: type: - string - 'null' format: date-time description: >- Timestamp when the API Key expires. Null means the key does not expire. 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 - expires_at - permissions - created_at - updated_at OrganizationApiKeyList: type: object properties: object: type: string description: Indicates this is a list response. const: list data: type: array items: $ref: '#/components/schemas/OrganizationApiKey' 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 OrganizationApiKeyWithValue: 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' format: date-time description: Timestamp of when the API Key was last used. example: null expires_at: type: - string - 'null' format: date-time description: >- Timestamp when the API Key expires. Null means the key does not expire. example: '2030-01-01T00:00:00.000Z' 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 - expires_at - permissions - created_at - updated_at - value Organization: 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 deprecated: true required: - object - id - name - domains - metadata - external_id - created_at - updated_at OrganizationList: type: object properties: 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: - object - data - list_metadata - list_metadata AuditLogConfiguration: type: object properties: organization_id: type: string description: Unique identifier of the Organization. example: org_01EHZNVPK3SFK441A1RGBFSHRT retention_period_in_days: type: integer 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 - Snowflake - 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 DataIntegrationAuthorizeUrlResponse: 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 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: 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 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: >- 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 PortalLinkResponse: type: object properties: link: type: string description: An ephemeral link to initiate the Admin Portal. example: >- https://setup.workos.com?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... required: - link RadarStandaloneResponse: 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 - 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 RadarListEntryAlreadyPresentResponse: type: object properties: message: type: string description: A message indicating the entry already exists. example: Entry already present in list required: - message RedirectUri: 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 UserlandUserAuthenticationFactorList: type: object properties: object: type: string description: Indicates this is a list response. const: list data: type: array items: $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/AuthenticationFactorEnrolled' 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: $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 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 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 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_01HYGBX8ZGD19949T3BM4FW1C3 accepted_user_id: type: - string - 'null' description: The ID of the user who accepted the invitation, once accepted. example: null role_slug: type: - string - 'null' description: >- Slug of the role the invitee will be assigned on acceptance. Reflects the current role on the invitee's organization membership. null when the invitation has no associated organization. example: admin 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 - role_slug - created_at - updated_at - token - accept_invitation_url UserlandUserOrganizationMembership: 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_01E4ZCR3C56J083X43JQXF3JK5 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. user: $ref: '#/components/schemas/UserlandUser' description: The user that belongs to the organization through this membership. required: - object - id - user_id - organization_id - status - directory_managed - created_at - updated_at - role - user UserApiKey: 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: user const: user id: type: string description: Unique identifier of the API Key owner. example: user_01EHZNVPK3SFK441A1RGBFSHRT organization_id: type: string description: Unique identifier of the organization the API Key can access. example: org_01EHZNVPK3SFK441A1RGBFSHRT required: - type - id - organization_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' format: date-time description: Timestamp of when the API Key was last used. example: null expires_at: type: - string - 'null' format: date-time description: >- Timestamp when the API Key expires. Null means the key does not expire. 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 - expires_at - permissions - created_at - updated_at UserApiKeyList: type: object properties: object: type: string description: Indicates this is a list response. const: list data: type: array items: $ref: '#/components/schemas/UserApiKey' 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 UserApiKeyWithValue: 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: user const: user id: type: string description: Unique identifier of the API Key owner. example: user_01EHZNVPK3SFK441A1RGBFSHRT organization_id: type: string description: Unique identifier of the organization the API Key can access. example: org_01EHZNVPK3SFK441A1RGBFSHRT required: - type - id - organization_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' format: date-time description: Timestamp of when the API Key was last used. example: null expires_at: type: - string - 'null' format: date-time description: >- Timestamp when the API Key expires. Null means the key does not expire. example: '2030-01-01T00:00:00.000Z' 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 - expires_at - permissions - created_at - updated_at - value UserlandUserList: type: object properties: object: type: string 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: - 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. 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 SendVerificationEmailResponse: type: object properties: user: $ref: '#/components/schemas/UserlandUser' description: The user to whom the verification email was sent. required: - user VerifyEmailResponse: type: object properties: user: $ref: '#/components/schemas/UserlandUser' description: The user whose email was verified. required: - user PasswordReset: 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 ResetPasswordResponse: type: object properties: user: $ref: '#/components/schemas/UserlandUser' description: The user whose password was reset. required: - user EmailChange: type: object properties: object: type: string description: Distinguishes the email change object. const: email_change user: $ref: '#/components/schemas/UserlandUser' new_email: type: string description: The new email address the user is changing to. example: new.email@example.com expires_at: format: date-time type: string description: The timestamp when the email change code expires. example: '2026-01-15T12:00:00.000Z' created_at: format: date-time type: string description: The timestamp when the email change challenge was created. example: '2026-01-15T12:00:00.000Z' required: - object - user - new_email - expires_at - created_at 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 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: integer 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 DeviceAuthorizationResponse: 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. example: 5 required: - device_code - user_code - verification_uri - expires_in WebhookEndpointJson: 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 WebhookEndpointList: type: object properties: 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: - 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: OktaSAML 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 name: type: - string - 'null' description: The user's full name. example: Todd Rundgren role: description: >- The role assigned to the user within the organization, if applicable. oneOf: - $ref: '#/components/schemas/SlimRole' - type: 'null' roles: description: >- The roles assigned to the user within the organization, if applicable. oneOf: - type: array items: $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: - object - id - organization_id - connection_id - connection_type - idp_id - email - first_name - last_name - name - raw_attributes SsoTokenResponse: 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: integer description: The lifetime of the access token in seconds. example: 600 profile: $ref: '#/components/schemas/Profile' 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: integer 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 SsoLogoutAuthorizeResponse: 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 JwksResponse: 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 security: - bearer: []