openapi: 3.1.1
info:
  title: WorkOS admin-portal user-management.authentication 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.authentication
  description: User authentication endpoints.
  x-displayName: User Authentication
paths:
  /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/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 to revoke. This can be extracted from the `sid` claim of the access token.
        schema:
          example: session_01H93ZY4F80QPBEZ1R5B2SHQG8
          type: string
      - name: return_to
        required: false
        in: query
        description: The URL to redirect the user to after session revocation.
        schema:
          example: https://example.com
          type: string
      responses:
        '200':
          headers:
            location:
              schema:
                type: string
                format: uri
          description: OK
        '302':
          headers:
            location:
              schema:
                type: string
                format: uri
          description: ''
        '422':
          description: Unprocessable Entity
          content:
            application/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
components:
  schemas:
    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
    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.
    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
    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
        return_to:
          type: string
          description: The URL to redirect the user to after session revocation.
          example: https://example.com
      required:
      - session_id
  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.