openapi: 3.1.1 info: title: WorkOS admin-portal user-management.users API description: WorkOS REST API version: '1.0' contact: name: WorkOS url: https://workos.com email: support@workos.com license: name: MIT url: https://opensource.org/license/MIT servers: - url: https://api.workos.com description: Production - url: https://api.workos-test.com description: Staging security: - bearer: [] tags: - name: user-management.users description: Manage users. x-displayName: Users paths: /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/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/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). Defaults to descending. 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: 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: 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 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). Defaults to descending. 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 components: schemas: 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 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. SendVerificationEmailResponse: type: object properties: user: $ref: '#/components/schemas/UserlandUser' description: The user to whom the verification email was sent. required: - user ConfirmEmailChangeDto: type: object properties: code: type: string description: The one-time code used to confirm the email change. example: '123456' required: - code 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 email_verified: type: boolean description: Whether the user's email has been verified. example: true metadata: type: - object - 'null' additionalProperties: type: string maxLength: 600 maxProperties: 50 example: 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 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: - 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: password: optional: true variants: plaintext: - password hashed: - password_hash - password_hash_type 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 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 PaginationOrder: type: string enum: - normal - desc - asc example: desc default: desc 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 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 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 ResetPasswordResponse: type: object properties: user: $ref: '#/components/schemas/UserlandUser' description: The user whose password was reset. required: - user VerifyEmailResponse: type: object properties: user: $ref: '#/components/schemas/UserlandUser' description: The user whose email was verified. required: - user SendEmailChangeDto: type: object properties: new_email: type: string description: The new email address to change to. example: new.email@example.com required: - new_email 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 VerifyEmailAddressDto: type: object properties: code: type: string description: The one-time email verification code. example: '123456' required: - code 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 email_verified: type: - boolean - 'null' description: Whether the user's email has been verified. example: true metadata: type: - object - 'null' additionalProperties: type: string maxLength: 600 maxProperties: 50 example: 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: - 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: password: optional: true variants: plaintext: - password hashed: - password_hash - password_hash_type 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.