openapi: 3.0.1
info:
  title: Logto API references Account center Experience API
  description: 'API references for Logto services.


    Note: The documentation is for Logto Cloud. If you are using Logto OSS, please refer to the response of `/api/swagger.json` endpoint on your Logto instance.'
  version: Cloud
servers:
- url: https://[tenant_id].logto.app/
  description: Logto endpoint address.
security:
- OAuth2:
  - all
tags:
- name: Experience
  description: The Experience endpoints allow end-users to interact with Logto for identity verification and profile completion.
paths:
  /api/experience:
    put:
      operationId: InitInteraction
      tags:
      - Experience
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - interactionEvent
              properties:
                interactionEvent:
                  type: string
                  enum:
                  - SignIn
                  - Register
                  - ForgotPassword
                captchaToken:
                  type: string
      responses:
        '204':
          description: A new experience interaction has been successfully initiated.
        '400':
          description: Bad Request
        '422':
          description: Unprocessable Content
      security: []
      summary: Init new interaction
      description: Init a new experience interaction with the given interaction type. Any existing interaction data will be cleared.
  /api/experience/interaction-event:
    put:
      operationId: UpdateInteractionEvent
      tags:
      - Experience
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - interactionEvent
              properties:
                interactionEvent:
                  type: string
                  enum:
                  - SignIn
                  - Register
                  - ForgotPassword
                  description: The type of the interaction event. Only `SignIn` and `Register` are supported.
      responses:
        '204':
          description: The interaction event has been successfully updated.
        '400':
          description: The interaction event is invalid or cannot be updated.  Only `SignIn` and `Register` are interchangeable. If the current interaction event is `ForgotPassword`, it cannot be updated.
        '403':
          description: The given interaction event is not enabled in the sign-in experience settings.
      security: []
      summary: Update interaction event
      description: Update the current experience interaction event to the given event type. This API is used to switch the interaction event between `SignIn` and `Register`, while keeping all the verification records data.
  /api/experience/identification:
    post:
      operationId: IdentifyUser
      tags:
      - Experience
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                verificationId:
                  type: string
                  description: 'The ID of the verification record used to identify the user. <br/>- For `SignIn` and `ForgotPassword` interactions: Required to verify the user''s identity. <br/>- For `Register` interaction: Optional. If provided, new profile(s) will be attached to the registration session using the information from the verification record and trigger the account creation attempt. If not provided, the user account creation attempt will be triggered using the existing profile data in the interaction.'
                linkSocialIdentity:
                  type: boolean
                  description: Applies only to the SignIn interaction and is used when a SocialVerification type verification ID is provided. <br/>- If `true`, the user is identified using the verified email or phone number from the social identity provider, and the social identity is linked to the user's account. <br/>- If `false` or not provided, the API identifies the user solely through the social identity. <br/>This parameter is used to link a non-existing social identity to a related user account identified by the verified email or phone number.
      responses:
        '201':
          description: '`Register` interaction: The user account has been successfully created and identified.'
          content:
            application/json: {}
        '204':
          description: '`SignIn` and `ForgotPassword` interactions: The user has been successfully identified.'
        '400':
          description: The provided verificationId is invalid, not verified, or cannot be used to identify the user. <br/>- `session.verification_failed:` The verification is not verified or can not be used to identify the user. <br/>- `guard.invalid_target:` The `verificationId` is missing, but required for the `SignIn` and `ForgotPassword` interactions.
        '401':
          description: The user is suspended or banned from the service. (SignIn and ForgotPassword only)
        '403':
          description: The `SignIn` or `Register` interaction is disabled in the experience settings.
        '404':
          description: 'Entity not found. <br/>- `session.verification_session_not_found:` The verification record is not found.  <br/>- `user.user_not_exist:` The user account is not found (SignIn and ForgotPassword only).  '
        '409':
          description: The interaction has already been identified with a different user account.
        '422':
          description: The user account cannot be created due to validation errors, check error message for more details (Register only). <br/>- `user.<identifier>_already_in_use:` The given identifier is already in use by another user account. <br/>- `user.missing_profile:` Sign-in experience required user identifier or profile data is missing. (Register only)
      security: []
      summary: Identify user for the current interaction
      description: 'This API identifies the user based on the verificationId within the current experience interaction: <br/>- `SignIn` and `ForgotPassword` interactions: Verifies the user''s identity using the provided `verificationId`. <br/>- `Register` interaction: Creates a new user account using the profile data from the current interaction. If a verificationId is provided, the profile data will first be updated with the verification record before creating the account. If not, the account is created directly from the stored profile data.'
  /api/experience/submit:
    post:
      operationId: SubmitInteraction
      tags:
      - Experience
      parameters: []
      responses:
        '200':
          description: The interaction has been successfully submitted.
          content:
            application/json:
              schema:
                type: object
                required:
                - redirectTo
                properties:
                  redirectTo:
                    type: string
        '400':
          description: Bad Request
        '403':
          description: Multi-Factor Authentication (MFA) is enabled for the user but has not been verified.
        '404':
          description: 'The user has not been identified. '
        '422':
          description: The user profile can not been processed, check error message for more details. <br/>- The profile data is invalid or conflicts with existing user data. <br/>- Required profile data is missing. <br/>- The profile data is already in use by another user account.
      security: []
      summary: Submit interaction
      description: Submit the current interaction. <br/>- Submit the verified user identity to the OIDC provider for further authentication (SignIn and Register). <br/>- Update the user's profile data if any (SignIn and Register). <br/>- Reset the password and clear all the interaction records (ForgotPassword).
  /api/experience/interaction:
    get:
      operationId: GetInteraction
      tags:
      - Experience
      parameters: []
      responses:
        '200':
          description: The public interaction data has been successfully retrieved.
          content:
            application/json:
              schema:
                type: object
                required:
                - interactionEvent
                - profile
                properties:
                  interactionEvent:
                    type: string
                    enum:
                    - SignIn
                    - Register
                    - ForgotPassword
                  userId:
                    type: string
                  profile:
                    type: object
                    properties:
                      avatar:
                        type: string
                        maxLength: 2048
                        nullable: true
                      name:
                        type: string
                        maxLength: 128
                        nullable: true
                      username:
                        type: string
                        maxLength: 128
                        nullable: true
                      primaryEmail:
                        type: string
                        maxLength: 128
                        nullable: true
                      primaryPhone:
                        type: string
                        maxLength: 128
                        nullable: true
                      profile:
                        type: object
                        properties:
                          familyName:
                            type: string
                          givenName:
                            type: string
                          middleName:
                            type: string
                          nickname:
                            type: string
                          preferredUsername:
                            type: string
                          profile:
                            type: string
                          website:
                            type: string
                          gender:
                            type: string
                          birthdate:
                            type: string
                          zoneinfo:
                            type: string
                          locale:
                            type: string
                          address:
                            type: object
                            properties:
                              formatted:
                                type: string
                              streetAddress:
                                type: string
                              locality:
                                type: string
                              region:
                                type: string
                              postalCode:
                                type: string
                              country:
                                type: string
                      customData:
                        type: object
                        description: arbitrary
                      socialIdentity:
                        type: object
                        required:
                        - target
                        - userInfo
                        properties:
                          target:
                            type: string
                          userInfo:
                            type: object
                            required:
                            - id
                            properties:
                              id:
                                type: string
                              email:
                                type: string
                              phone:
                                type: string
                              name:
                                type: string
                              avatar:
                                type: string
                              rawData:
                                type: object
                                oneOf:
                                - type: object
                                  description: arbitrary JSON object
                                - type: array
                                  items:
                                    oneOf:
                                    - type: string
                                    - type: number
                                    - type: boolean
                                    - type: string
                                      nullable: true
                                      description: null value
                                    - type: object
                                      description: arbitrary JSON object
                                - type: string
                                - type: number
                                - type: boolean
                                nullable: true
                      enterpriseSsoIdentity:
                        type: object
                        required:
                        - identityId
                        - ssoConnectorId
                        - issuer
                        - detail
                        properties:
                          identityId:
                            type: string
                            minLength: 1
                            maxLength: 128
                          ssoConnectorId:
                            type: string
                            minLength: 1
                            maxLength: 128
                          issuer:
                            type: string
                            minLength: 1
                            maxLength: 256
                          detail:
                            type: object
                            description: arbitrary
                      syncedEnterpriseSsoIdentity:
                        type: object
                        required:
                        - identityId
                        - issuer
                        - detail
                        properties:
                          identityId:
                            type: string
                            minLength: 1
                            maxLength: 128
                          issuer:
                            type: string
                            minLength: 1
                            maxLength: 256
                          detail:
                            type: object
                            description: arbitrary
                      jitOrganizationIds:
                        type: array
                        items:
                          type: string
                      submitted:
                        type: boolean
                  verificationRecords:
                    type: array
                    items:
                      oneOf:
                      - type: object
                        required:
                        - id
                        - type
                        - identifier
                        - verified
                        properties:
                          id:
                            type: string
                          type:
                            type: string
                            format: '"Password"'
                          identifier:
                            type: object
                            required:
                            - type
                            - value
                            properties:
                              type:
                                oneOf:
                                - type: string
                                  enum:
                                  - username
                                  - email
                                  - phone
                                - type: string
                                  enum:
                                  - userId
                              value:
                                type: string
                          verified:
                            type: boolean
                      - type: object
                        required:
                        - id
                        - templateType
                        - verified
                        - type
                        - identifier
                        properties:
                          id:
                            type: string
                          templateType:
                            type: string
                            enum:
                            - SignIn
                            - Register
                            - ForgotPassword
                            - OrganizationInvitation
                            - Generic
                            - UserPermissionValidation
                            - BindNewIdentifier
                            - MfaVerification
                            - BindMfa
                          verified:
                            type: boolean
                          type:
                            type: string
                            format: '"EmailVerificationCode"'
                          identifier:
                            type: object
                            required:
                            - type
                            - value
                            properties:
                              type:
                                type: string
                                format: '"email"'
                              value:
                                type: string
                      - type: object
                        required:
                        - id
                        - templateType
                        - verified
                        - type
                        - identifier
                        properties:
                          id:
                            type: string
                          templateType:
                            type: string
                            enum:
                            - SignIn
                            - Register
                            - ForgotPassword
                            - OrganizationInvitation
                            - Generic
                            - UserPermissionValidation
                            - BindNewIdentifier
                            - MfaVerification
                            - BindMfa
                          verified:
                            type: boolean
                          type:
                            type: string
                            format: '"PhoneVerificationCode"'
                          identifier:
                            type: object
                            required:
                            - type
                            - value
                            properties:
                              type:
                                type: string
                                format: '"phone"'
                              value:
                                type: string
                      - type: object
                        required:
                        - id
                        - templateType
                        - verified
                        - type
                        - identifier
                        properties:
                          id:
                            type: string
                          templateType:
                            type: string
                            enum:
                            - SignIn
                            - Register
                            - ForgotPassword
                            - OrganizationInvitation
                            - Generic
                            - UserPermissionValidation
                            - BindNewIdentifier
                            - MfaVerification
                            - BindMfa
                          verified:
                            type: boolean
                          type:
                            type: string
                            format: '"MfaEmailVerificationCode"'
                          identifier:
                            type: object
                            required:
                            - type
                            - value
                            properties:
                              type:
                                type: string
                                format: '"email"'
                              value:
                                type: string
                      - type: object
                        required:
                        - id
                        - templateType
                        - verified
                        - type
                        - identifier
                        properties:
                          id:
                            type: string
                          templateType:
                            type: string
                            enum:
                            - SignIn
                            - Register
                            - ForgotPassword
                            - OrganizationInvitation
                            - Generic
                            - UserPermissionValidation
                            - BindNewIdentifier
                            - MfaVerification
                            - BindMfa
                          verified:
                            type: boolean
                          type:
                            type: string
                            format: '"MfaPhoneVerificationCode"'
                          identifier:
                            type: object
                            required:
                            - type
                            - value
                            properties:
                              type:
                                type: string
                                format: '"phone"'
                              value:
                                type: string
                      - type: object
                        required:
                        - id
                        - connectorId
                        - type
                        properties:
                          id:
                            type: string
                          connectorId:
                            type: string
                          type:
                            type: string
                            format: '"Social"'
                          socialUserInfo:
                            type: object
                            required:
                            - id
                            properties:
                              id:
                                type: string
                              email:
                                type: string
                              phone:
                                type: string
                              name:
                                type: string
                              avatar:
                                type: string
                              rawData:
                                type: object
                                oneOf:
                                - type: object
                                  description: arbitrary JSON object
                                - type: array
                                  items:
                                    oneOf:
                                    - type: string
                                    - type: number
                                    - type: boolean
                                    - type: string
                                      nullable: true
                                      description: null value
                                    - type: object
                                      description: arbitrary JSON object
                                - type: string
                                - type: number
                                - type: boolean
                                nullable: true
                      - type: object
                        required:
                        - id
                        - connectorId
                        - type
                        properties:
                          id:
                            type: string
                          connectorId:
                            type: string
                          type:
                            type: string
                            format: '"EnterpriseSso"'
                          enterpriseSsoUserInfo:
                            type: object
                            required:
                            - id
                            properties:
                              id:
                                type: string
                              email:
                                type: string
                              phone:
                                type: string
                              name:
                                type: string
                              avatar:
                                type: string
                              rawData:
                                type: object
                                oneOf:
                                - type: object
                                  description: arbitrary JSON object
                                - type: array
                                  items:
                                    oneOf:
                                    - type: string
                                    - type: number
                                    - type: boolean
                                    - type: string
                                      nullable: true
                                      description: null value
                                    - type: object
                                      description: arbitrary JSON object
                                - type: string
                                - type: number
                                - type: boolean
                                nullable: true
                          issuer:
                            type: string
                      - type: object
                        required:
                        - id
                        - type
                        - userId
                        - verified
                        properties:
                          id:
                            type: string
                          type:
                            type: string
                            format: '"Totp"'
                          userId:
                            type: string
                          verified:
                            type: boolean
                      - type: object
                        required:
                        - id
                        - type
                        - userId
                        properties:
                          id:
                            type: string
                          type:
                            type: string
                            format: '"BackupCode"'
                          userId:
                            type: string
                          code:
                            type: string
                      - type: object
                        required:
                        - id
                        - verified
                        - type
                        - userId
                        properties:
                          id:
                            type: string
                          verified:
                            type: boolean
                          type:
                            type: string
                            format: '"WebAuthn"'
                          userId:
                            type: string
                      - type: object
                        required:
                        - id
                        - verified
                        - type
                        properties:
                          id:
                            type: string
                          verified:
                            type: boolean
                          type:
                            type: string
                            format: '"SignInPasskey"'
                          userId:
                            type: string
                      - type: object
                        required:
                        - id
                        - type
                        - identifier
                        properties:
                          id:
                            type: string
                          type:
                            type: string
                            format: '"NewPasswordIdentity"'
                          identifier:
                            type: object
                            required:
                            - type
                            - value
                            properties:
                              type:
                                type: string
                                enum:
                                - username
                                - email
                                - phone
                              value:
                                type: string
                      - type: object
                        required:
                        - id
                        - type
                        - verified
                        - identifier
                        properties:
                          id:
                            type: string
                          type:
                            type: string
                            format: '"OneTimeToken"'
                          verified:
                            type: boolean
                          identifier:
                            type: object
                            required:
                            - type
                            - value
                            properties:
                              type:
                                type: string
                                format: '"email"'
                              value:
                                type: string
                          oneTimeTokenContext:
                            type: object
                            properties:
                              jitOrganizationIds:
                                type: array
                                items:
                                  type: string
                  mfa:
                    type: object
                    properties:
                      mfaEnabled:
                        type: boolean
                      mfaSkipped:
                        type: boolean
                      passkeySkipped:
                        type: boolean
                      totp:
                        type: object
                        required:
                        - type
                        properties:
                          type:
                            type: string
                            format: '"Totp"'
                      webAuthn:
                        type: array
                        items:
                          type: object
                          required:
                          - type
                          - rpId
                          - credentialId
                          - publicKey
                          - transports
                          - counter
                          - agent
                          properties:
                            type:
                              type: string
                              format: '"WebAuthn"'
                            rpId:
                              type: string
                            credentialId:
                              type: string
                            publicKey:
                              type: string
                            transports:
                              type: array
                              items:
                                type: string
                                enum:
                                - usb
                                - nfc
                                - ble
                                - internal
                                - cable
                                - hybrid
                                - smart-card
                            counter:
                              type: number
                            agent:
                              type: string
                            name:
                              type: string
                      backupCode:
                        type: object
                        required:
                        - type
                        properties:
                          type:
                            type: string
                            format: '"BackupCode"'
                  signInContext:
                    type: object
                    additionalProperties:
                      type: string
                  captcha:
                    type: object
                    required:
                    - verified
                    - skipped
                    properties:
                      verified:
                        type: boolean
                      skipped:
                        type: boolean
      security: []
      summary: Get public interaction data
      description: Get the public interaction data.
  /api/experience/verification/password:
    post:
      operationId: CreatePasswordVerification
      tags:
      - Experience
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - identifier
              - password
              properties:
                identifier:
                  type: object
                  required:
                  - type
                  - value
                  properties:
                    type:
                      type: string
                      enum:
                      - username
                      - email
                      - phone
                    value:
                      type: string
                  description: The unique identifier of the user that will be used to identify the user along with the provided password.
                password:
                  type: string
                  minLength: 1
                  description: The user password.
      responses:
        '200':
          description: The Password verification record has been successfully created and verified.
          content:
            application/json:
              schema:
                type: object
                required:
                - verificationId
                properties:
                  verificationId:
                    type: string
                    description: The unique verification ID of the newly created Password verification record. The `verificationId` is required when verifying the user's identity via the `Identification` API.
        '400':
          description: The verification attempts have exceeded the maximum limit.
        '401':
          description: The user is suspended or banned from the service.
        '422':
          description: '`session.invalid_credentials:` Either the user is not found or the provided password is incorrect.'
      security: []
      summary: Create password verification record
      description: Create and verify a new Password verification record. The verification record can only be created if the provided user credentials are correct.
  /api/experience/verification/verification-code:
    post:
      operationId: CreateAndSendVerificationCode
      tags:
      - Experience
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - identifier
              - interactionEvent
              properties:
                identifier:
                  oneOf:
                  - type: object
                    required:
                    - type
                    - value
                    properties:
                      type:
                        type: string
                        format: '"email"'
                      value:
                        type: string
                        format: regex
                        pattern: /^\S+@\S+\.\S+$/
                  - type: object
                    required:
                    - type
                    - value
                    properties:
                      type:
                        type: string
                        format: '"phone"'
                      value:
                        type: string
                        format: regex
                        pattern: /^\d+$/
                  description: The identifier (email address or phone number) to send the verification code to.
                interactionEvent:
                  type: string
                  enum:
                  - SignIn
                  - Register
                  - ForgotPassword
                  description: The interaction event for which the verification code will be used. Supported values are `SignIn`, `Register`, and `ForgotPassword`. This determines the template for the verification code.
      responses:
        '200':
          description: The verification code has been successfully sent.
          content:
            application/json:
              schema:
                type: object
                required:
                - verificationId
                properties:
                  verificationId:
                    type: string
                    description: The unique ID of the verification record. Required to verify the code.
        '400':
          description: An invalid identifier was provided.
        '404':
          description: Not Found
        '422':
          description: Unprocessable Content
        '501':
          description: The connector for sending the verification code is not configured.
      security: []
      summary: Create and send verification code
      description: Create a new `CodeVerification` record and sends the code to the specified identifier. The code verification can be used to verify the given identifier.
  /api/experience/verification/verification-code/verify:
    post:
      operationId: VerifyVerificationCodeVerification
      tags:
      - Experience
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - identifier
              - verificationId
              - code
              properties:
                identifier:
                  oneOf:
                  - type: object
                    required:
                    - type
                    - value
                    properties:
                      type:
                        type: string
                        format: '"email"'
                      value:
                        type: string
                        format: regex
                        pattern: /^\S+@\S+\.\S+$/
                  - type: object
                    required:
                    - type
                    - value
                    properties:
                      type:
                        type: string
                        format: '"phone"'
                      value:
                        type: string
                        format: regex
                        pattern: /^\d+$/
                  description: The identifier (email address or phone number) to verify the code against. Must match the identifier used to send the verification code.
                verificationId:
                  type: string
                  description: The verification ID of the CodeVerification record.
                code:
                  type: string
                  description: The verification code to be verified.
      responses:
        '200':
          description: The verification code was successfully verified.
          content:
            application/json:
              schema:
                type: object
                required:
                - verificationId
                properties:
                  verificationId:
                    type: string
                    description: The unique ID of the verification record. Required for user identification via the `Identification` API or to bind the identifier to the user's account via the `Profile` API.
        '400':
          description: The verification code is invalid or the maximum number of attempts has been exceeded. Check the error message for details.
        '404':
          description: Verification record not found.
        '501':
          description: The connector for sending the verification code is not configured.
      security: []
      summary: Verify verification code
      description: Verify the provided verification code against the user's identifier. If successful, the verification record will be marked as verified.
  /api/experience/verification/mfa-verification-code:
    post:
      operationId: CreateAndSendMfaVerificationCode
      tags:
      - Experience
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - identifierType
              properties:
                identifierType:
                  type: string
                  enum:
                  - email
                  - phone
                  - Email
                  - Phone
                  description: The type of identifier to use for MFA verification. Must be either 'Email' or 'Phone'. The endpoint will automatically use the user's bound identifier of this type.
      responses:
        '200':
          description: The MFA verification code has been successfully sent to the user's bound identifier.
          content:
            application/json:
              schema:
                type: object
                required:
                - verificationId
                properties:
                  verificationId:
                    type: string
                    description: The unique ID of the verification record. Required to verify the code.
        '400':
          description: Bad request. The user is not identified or does not have the specified identifier type bound for MFA.
        '404':
          description: User not found.
        '501':
          description: The connector for the specified identifier type is not configured.
      security: []
      summary: Create and send MFA verification code
      description: Create a new MFA verification code and send it to the user's bound identifier (email or phone). This endpoint automatically uses the user's bound email address or phone number from their profile for MFA verification. The user must be identified before calling this endpoint.
  /api/experience/verification/mfa-verification-code/verify:
    post:
      operationId: VerifyMfaVerificationCode
      tags:
      - Experience
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - verificationId
              - code
              - identifierType
              properties:
                verificationId:
                  type: string
                  description: The verification ID returned from the MFA verification code send endpoint.
                code:
                  type: string
                  description: The verification code received by the user.
                identifierType:
                  type: string
                  enum:
                  - email
                  - phone
                  - Email
                  - Phone
                  description: The type of identifier used for MFA verification. Must match the type used when sending the verification code.
      responses:
        '200':
          description: The MFA verification code was successfully verified.
          content:
            application/json:
              schema:
                type: object
                required:
                - verificationId
                properties:
                  verificationId:
                    type: string
                    description: The unique ID of the verification record. This can be used for subsequent MFA operations.
        '400':
          description: Bad request. The verification code is invalid, expired, or the user is not identified.
        '404':
          description: Verification record not found.
        '501':
          description: The connector for the verification method is not configured.
      security: []
      summary: Verify MFA verification code
      description: Verify the provided MFA verification code. The verification code must have been sent using the MFA verification code endpoint. This endpoint verifies the code against the user's bound identifier and marks the verification as complete if successful.
  /api/experience/verification/social/{connectorId}/authorization-uri:
    post:
      operationId: CreateSocialVerification
      tags:
      - Experience
      parameters:
      - $ref: '#/components/parameters/connectorId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - state
              - redirectUri
              properties:
                state:
                  type: string
                  description: The state parameter to pass to the social connector.
                redirectUri:
                  type: string
                  description: The URI to redirect the user after the social authorization is completed.
      responses:
        '200':
          description: The social authorization URI has been successfully generated.
          content:
            application/json:
              schema:
                type: object
                required:
                - authorizationUri
                - verificationId
                properties:
                  authorizationUri:
                    type: string
                    description: The social authorization URI.
                  verificationId:
                    type: string
                    description: The unique verification ID of the newly created SocialVerification record. The `verificationId` is required when verifying the social authorization response.
        '400':
          description: Bad Request
        '404':
          description: The social connector is not found.
        '500':
          description: Connector error. Failed to generate the social authorization URI.
      security: []
      summary: Create social verification
      description: Create a new SocialVerification record and return the provider's authorization URI for the given connector.
  /api/experience/verification/social/{connectorId}/verify:
    post:
      operationId: VerifySocialVerification
      tags:
      - Experience
      parameters:
      - $ref: '#/components/parameters/connectorId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - connectorData
              properties:
                connectorData:
                  type: object
                  description: Arbitrary data returned by the social provider to complete the verification process.
                verificationId:
                  type: string
                  description: The ID of the social verification record. Optional for Google one tap login, as it does not have a pre-created social verification record in session.
      responses:
        '200':
          description: The social authorization response has been successfully verified.
          content:
            application/json:
              schema:
                type: object
                required:
                - verificationId
                properties:
                  verificationId:
                    type: string
                    description: The unique verification ID of the SocialVerification record. This ID is required when identifying the user in the current interaction.
        '400':
          description: The social authorization response is invalid or cannot be verified.
        '404':
          description: The social connector is not found.
        '500':
          description: Connector error. Failed to verify the social authorization response or fetch the user info from the social provider.
      security: []
      summary: Verify social verification
      description: Verify the social authorization response data and get the user's identity data from the social provider.
  /api/experience/verification/sso/{connectorId}/authorization-uri:
    post:
      operationId: CreateEnterpriseSsoVerification
      tags:
      - Experience
      parameters:
      - $ref: '#/components/parameters/connectorId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - state
              - redirectUri
              properties:
                state:
                  type: string
                  description: The state parameter to pass to the SSO connector.
                redirectUri:
                  type: string
                  description: The URI to redirect the user after the SSO authorization is completed.
      responses:
        '200':
          description: The SSO authorization URI has been successfully generated.
          content:
            application/json:
              schema:
                type: object
                required:
                - authorizationUri
                - verificationId
                properties:
                  authorizationUri:
                    type: string
                    description: The SSO authorization URI.
                  verificationId:
                    type: string
                    description: The unique verification ID of the newly created EnterpriseSSO verification record. The `verificationId` is required when verifying the SSO authorization response.
        '400':
          description: Bad Request
        '404':
          description: The SSO connector is not found.
        '500':
          description: Connector error. Failed to generate the SSO authorization URI.
      security: []
      summary: Create enterprise SSO verification
      description: Create a new EnterpriseSSO verification record and return the provider's authorization URI for the given connector.
  /api/experience/verification/sso/{connectorId}/verify:
    post:
      operationId: VerifyEnterpriseSsoVerification
      tags:
      - Experience
      parameters:
      - $ref: '#/components/parameters/connectorId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - connectorData
              - verificationId
              properties:
                connectorData:
                  type: object
                  description: Arbitrary data returned by the SSO provider to complete the verification process.
                verificationId:
                  type: string
                  description: The ID of the EnterpriseSSO verification record.
      responses:
        '200':
          description: The SSO authorization response has been successfully verified.
          content:
            application/json:
              schema:
                type: object
                required:
                - verificationId
                properties:
                  verificationId:
                    type: string
                    description: The current verified EnterpriseSSO verification record ID. This ID is required when identifying the user in the current interaction.
        '400':
          description: The SSO authorization response is invalid or cannot be verified.
        '404':
          description: The verification record or the SSO connector is not found.
        '500':
          description: Connector error. Failed to verify the SSO authorization response or fetch the user info from the SSO provider.
      security: []
      summary: Verify enterprise SSO verification
      description: Verify the SSO authorization response data and get the user's identity from the SSO provider.
  /api/experience/verification/totp/secret:
    post:
      operationId: CreateTotpSecret
      tags:
      - Experience
      parameters: []
      responses:
        '200':
          description: TOTP secret successfully generated.
          content:
            application/json:
              schema:
                type: object
                required:
                - verificationId
                - secret
                - secretQrCode
                properties:
                  verificationId:
                    type: string
                    description: The unique verification ID for the TOTP record. This ID is required to verify the TOTP code.
                  secret:
                    type: string
                    description: The newly generated TOTP secret.
                  secretQrCode:
                    type: string
                    description: A QR code image data URL for the TOTP secret. The user can scan this QR code with their TOTP authenticator app.
        '400':
          description: Bad Request
        '404':
          description: Entity not found. <br/> - `session.identifier_not_found:` The current interaction is not identified yet. All MFA verification records must be associated with a identified user.
      security: []
      summary: Create TOTP secret
      description: Create a new TOTP verification record and generate a new TOTP secret for the user. This secret can be used to bind a new TOTP verification to the user's profile. The verification record must be verified before the secret can be used to bind a new TOTP verification to the user's profile.
  /api/experience/verification/totp/verify:
    post:
      operationId: VerifyTotpVerification
      tags:
      - Experience
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - code
              properties:
                code:
                  type: string
                  minLength: 1
                  description: The TOTP code to be verified.
                verificationId:
                  type: string
                  description: The verification ID of the newly created TOTP secret. This ID is required to verify a newly created TOTP secret that needs to be bound to the user account. If not provided, the API will create a new TOTP verification record and verify the code against the user's existing TOTP secret.
      responses:
        '200':
          description: The TOTP code has been successfully verified.
          content:
            application/json:
              schema:
                type: object
                required:
                - verificationId
                properties:
                  verificationId:
                    type: string
                    description: The unique verification ID of the TOTP verification record. For newly created TOTP secret verification record, this ID is required to bind the TOTP secret to the user account through `Profile` API.
        '400':
          description: Invalid TOTP code.
        '404':
          description: Verification record not found.
      security: []
      summary: Verify TOTP verification
      description: Verifies the provided TOTP code against the new created TOTP secret or the existing TOTP secret. If a verificationId is provided, this API will verify the code against the TOTP secret that is associated with the verification record. Otherwise, a new TOTP verification record will be created and verified against the user's existing TOTP secret.
  /api/experience/verification/web-authn/registration:
    post:
      operationId: CreateWebAuthnRegistrationVerification
      tags:
      - Experience
      parameters: []
      responses:
        '200':
          description: WebAuthn registration successfully created.
          content:
            application/json:
              schema:
                type: object
                required:
                - verificationId
                - registrationOptions
                properties:
                  verificationId:
                    type: string
                    description: The unique verification ID for the WebAuthn registration record. This ID is required to verify the WebAuthn registration challenge.
                  registrationOptions:
                    type: object
                    required:
                    - rp
                    - user
                    - challenge
                    - pubKeyCredParams
                    properties:
                      rp:
                        type: object
                        required:
                        - name
                        properties:
                          name:
                            type: string
                          id:
                            type: string
                      user:
                        type: object
                        required:
                        - id
                        - name
                        - displayName
                        properties:
                          id:
                            type: string
                          name:
                            type: string
                          displayName:
                            type: string
                      challenge:
                        type: string
                      pubKeyCredParams:
                        type: array
                        items:
                          type: object
                          required:
                          - type
                          - alg
                          properties:
                            type:
                              type: string
                              format: '"public-key"'
                            alg:
                              type: number
                      timeout:
                        type: number
                      excludeCredentials:
                        type: array
                        items:
                          type: object
                          required:
                          - type
                          - id
                          properties:
                            type:
                              type: string
                              format: '"public-key"'
                            id:
                              type: string
                            transports:
                              type: array
                              items:
                                type: string
                                enum:
                                - usb
                                - nfc
                                - ble
                                - internal
                                - cable
                                - hybrid
                                - smart-card
                      authenticatorSelection:
                        type: object
                        properties:
                          authenticatorAttachment:
                            type: string
                            enum:
                            - platform
                            - cross-platform
                          requireResidentKey:
                            type: boolean
                          residentKey:
                            type: string
                            enum:
                            - discouraged
                            - preferred
                            - required
                          userVerification:
                            type: string
                            enum:
                            - required
                            - preferred
                            - discouraged
                      attestation:
                        type: string
                        enum:
                        - none
                        - indirect
                        - direct
                        - enterprise
                      extensions:
                        type: object
                        properties:
                          appid:
                            type: string
                          credProps:
                            type: boolean
                          hmacCreateSecret:
                            type: boolean
                    description: The WebAuthn registration options that the user needs to create a new WebAuthn credential.
        '400':
          description: Bad Request
        '404':
          description: Entity not found. <br/> - `session.identifier_not_found:` The current interaction is not identified yet. All MFA verification records must be associated with a identified user.
      security: []
      summary: Create WebAuthn registration verification
      description: Create a new WebAuthn registration verification record. The verification record can be used to bind a new WebAuthn credential to the user's profile.
  /api/experience/verification/web-authn/registration/verify:
    post:
      operationId: VerifyWebAuthnRegistrationVerification
      tags:
      - Experience
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - verificationId
              - payload
              properties:
                verificationId:
                  type: string
                  description: The verification ID of the WebAuthn registration record.
                payload:
                  type: object
                  required:
                  - type
                  - id
                  - rawId
                  - response
                  - clientExtensionResults
                  properties:
                    type:
                      type: string
                      format: '"WebAuthn"'
                    id:
                      type: string
                    rawId:
                      type: string
                    response:
                      type: object
                      required:
                      - clientDataJSON
                      - attestationObject
                      properties:
                        clientDataJSON:
                          type: string
                        attestationObject:
                          type: string
                        authenticatorData:
                          type: string
                        transports:
                          type: array
                          items:
                            type: string
                            enum:
                            - usb
                            - nfc
                            - ble
                            - internal
                            - cable
                            - hybrid
                            - smart-card
                        publicKeyAlgorithm:
                          type: number
                        publicKey:
                          type: string
                    authenticatorAttachment:
                      type: string
                      enum:
                      - cross-platform
                      - platform
                    clientExtensionResults:
                      type: object
                      properties:
                        appid:
                          type: boolean
                        crepProps:
                          type: object
                          properties:
                            rk:
                              type: boolean
                        hmacCreateSecret:
                          type: boolean
                  description: The WebAuthn attestation response from the user's WebAuthn credential.
      responses:
        '200':
          description: The WebAuthn registration has been successfully verified.
          content:
            application/json:
              schema:
                type: object
                required:
                - verificationId
                properties:
                  verificationId:
                    type: string
                    description: The unique verification ID of the WebAuthn registration record. This `verificationId` is required to bind the WebAuthn credential to the user account via the `Profile` API.
        '400':
          description: Invalid request. <br/>  - `session.mfa.pending_info_not_found:` The WebAuthn registration challenge is missing from the current verification record. <br/>- `session.mfa.webauthn_verification_failed:` The WebAuthn attestation response is invalid or cannot be verified.
        '404':
          description: Verification record not found.
      security: []
      summary: Verify WebAuthn registration verification
      description: Verify the WebAuthn registration response against the user's WebAuthn registration challenge. If the response is valid, the WebAuthn registration record will be marked as verified.
  /api/experience/verification/web-authn/authentication:
    post:
      operationId: CreateWebAuthnAuthenticationVerification
      tags:
      - Experience
      parameters: []
      responses:
        '200':
          description: WebAuthn authentication successfully initiated.
          content:
            application/json:
              schema:
                type: object
                required:
                - verificationId
                - authenticationOptions
                properties:
                  verificationId:
                    type: string
                    description: The unique ID for the WebAuthn authentication record, required to verify the WebAuthn authentication challenge.
                  authenticationOptions:
                    type: object
                    required:
                    - challenge
                    properties:
                      challenge:
                        type: string
                      timeout:
                        type: number
                      rpId:
                        type: string
                      allowCredentials:
                        type: array
                        items:
                          type: object
                          required:
                          - type
                          - id
                          properties:
                            type:
                              type: string
                              format: '"public-key"'
                            id:
                              type: string
                            transports:
                              type: array
                              items:
                                type: string
                                enum:
                                - usb
                                - nfc
                                - ble
                                - internal
                                - cable
                                - hybrid
                                - smart-card
                      userVerification:
                        type: string
                        enum:
                        - required
                        - preferred
                        - discouraged
                      extensions:
                        type: object
                        properties:
                          appid:
                            type: string
                          credProps:
                            type: boolean
                          hmacCreateSecret:
                            type: boolean
                    description: Options for the user to authenticate with their WebAuthn credential.
        '400':
          description: The user does not have a verified WebAuthn credential.
        '404':
          description: The current interaction is not yet identified. All MFA verification records must be associated with an identified user.
      security: []
      summary: Create WebAuthn authentication verification
      description: Create a new WebAuthn authentication verification record based on the user's existing WebAuthn credential. This verification record can be used to verify the user's WebAuthn credential.
  /api/experience/verification/web-authn/authentication/verify:
    post:
      operationId: VerifyWebAuthnAuthenticationVerification
      tags:
      - Experience
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - verificationId
              - payload
              properties:
                verificationId:
                  type: string
                  description: The verification ID of the WebAuthn authentication verification record.
                payload:
                  type: object
                  required:
                  - type
                  - id
                  - rawId
                  - clientExtensionResults
                  - response
                  properties:
                    type:
                      type: string
                      format: '"WebAuthn"'
                    id:
                      type: string
                    rawId:
                      type: string
                    authenticatorAttachment:
                      type: string
                      enum:
                      - cross-platform
                      - platform
                    clientExtensionResults:
                      type: object
                      properties:
                        appid:
                          type: boolean
                        crepProps:
                          type: object
                          properties:
                            rk:
                              type: boolean
                        hmacCreateSecret:
                          type: boolean
                    response:
                      type: object
                      required:
                      - clientDataJSON
                      - authenticatorData
                      - signature
                      properties:
                        clientDataJSON:
                          type: string
                        authenticatorData:
                          type: string
                        signature:
                          type: string
                        userHandle:
                          type: string
                  description: The WebAuthn assertion response from the user's WebAuthn credential.
      responses:
        '200':
          description: The WebAuthn authentication has been successfully verified.
          content:
            application/json:
              schema:
                type: object
                required:
                - verificationId
                properties:
                  verificationId:
                    type: string
                    description: The unique verification ID of the WebAuthn authentication verification record.
        '400':
          description: Invalid request. <br/> - `session.mfa.pending_info_not_found:` The WebAuthn authentication challenge is missing in the current verification record. <br/>- `session.mfa.webauthn_verification_failed:` The WebAuthn assertion response is invalid or cannot be verified.
        '404':
          description: Verification record not found.
      security: []
      summary: Verify WebAuthn authentication verification
      description: Verifies the WebAuthn authentication response against the user's authentication challenge. Upon successful verification, the verification record will be marked as verified.
  /api/experience/verification/sign-in-passkey/authentication:
    post:
      operationId: CreateSignInPasskeyAuthenticationWithIdentifier
      tags:
      - Experience
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - identifier
              properties:
                identifier:
                  type: object
                  required:
                  - type
                  - value
                  properties:
                    type:
                      type: string
                      enum:
                      - username
                      - email
                      - phone
                    value:
                      type: string
                  description: The identifier used to look up the user.
      responses:
        '200':
          description: Passkey sign-in WebAuthn authentication options have been successfully created.
          content:
            application/json:
              schema:
                type: object
                required:
                - verificationId
                - authenticationOptions
                properties:
                  verificationId:
                    type: string
                    description: The unique verification ID of the passkey sign-in WebAuthn authentication record.
                  authenticationOptions:
                    type: object
                    required:
                    - challenge
                    properties:
                      challenge:
                        type: string
                      timeout:
                        type: number
                      rpId:
                        type: string
                      allowCredentials:
                        type: array
                        items:
                          type: object
                          required:
                          - type
                          - id
                          properties:
                            type:
                              type: string
                              format: '"public-key"'
                            id:
                              type: string
                            transports:
                              type: array
                              items:
                                type: string
                                enum:
                                - usb
                                - nfc
                                - ble
                                - internal
                                - cable
                                - hybrid
                                - smart-card
                      userVerification:
                        type: string
                        enum:
                        - required
                        - preferred
                        - discouraged
                      extensions:
                        type: object
                        properties:
                          appid:
                            type: string
                          credProps:
                            type: boolean
                          hmacCreateSecret:
                            type: boolean
                    description: The WebAuthn authentication options for initiating passkey sign-in.
        '400':
          description: Invalid request.
        '404':
          description: User not found.
      security: []
      summary: Create passkey sign-in WebAuthn authentication with identifier
      description: Create WebAuthn authentication options for passkey sign-in with an identifier. The identifier is used to look up the user's WebAuthn credentials and generate non-discoverable authentication options.
  /api/experience/verification/sign-in-passkey/authentication/verify:
    post:
      operationId: VerifySignInPasskeyAuthentication
      tags:
      - Experience
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - payload
              properties:
                verificationId:
                  type: string
                  description: The verification ID of the passkey sign-in WebAuthn authentication record. Optional when using discoverable passkey flow with preflight authentication options.
                payload:
                  type: object
                  required:
                  - type
                  - id
                  - rawId
                  - clientExtensionResults
                  - response
                  properties:
                    type:
                      type: string
                      format: '"WebAuthn"'
                    id:
                      type: string
                    rawId:
                      type: string
                    authenticatorAttachment:
                      type: string
                      enum:
                      - cross-platform
                      - platform
                    clientExtensionResults:
                      type: object
                      properties:
                        appid:
                          type: boolean
                        crepProps:
                          type: object
                          properties:
                            rk:
                              type: boolean
                        hmacCreateSecret:
                          type: boolean
                    response:
                      type: object
                      required:
                      - clientDataJSON
                      - authenticatorData
                      - signature
                      properties:
                        clientDataJSON:
                          type: string
                        authenticatorData:
                          type: string
                        signature:
                          type: string
                        userHandle:
                          type: string
                  description: The WebAuthn assertion response from the user's passkey credential.
      responses:
        '200':
          description: The passkey sign-in WebAuthn authentication has been successfully verified.
          content:
            application/json:
              schema:
                type: object
                required:
                - verificationId
                properties:
                  verificationId:
                    type: string
                    description: The unique verification ID of the passkey sign-in WebAuthn authentication verification record.
        '400':
          description: Invalid request. <br/> - `session.mfa.pending_info_not_found:` The WebAuthn authentication challenge is missing in the current verification record. <br/>- `session.mfa.webauthn_verification_failed:` The WebAuthn assertion response is invalid or cannot be verified.
        '404':
          description: Verification session not found.
        '409':
          description: Identity conflict. <br/> - `session.identity_conflict:` The user associated with the verified WebAuthn credential does not match the identified user in the current interaction.
      security: []
      summary: Verify passkey sign-in WebAuthn authentication
      description: Verify the passkey sign-in WebAuthn authentication response against the stored authentication challenge. When `verificationId` is provided, it verifies against the challenge generated by the identifier-based authentication endpoint. When omitted, it verifies against the preflight authentication options stored in the interaction. Upon successful verification, the verification record will be marked as verified and the user will be resolved by the credential if not provided earlier.
  /api/experience/verification/backup-code/generate:
    post:
      operationId: GenerateBackupCodes
      tags:
      - Experience
      parameters: []
      responses:
        '200':
          description: Backup codes have been successfully generated.
          content:
            application/json:
              schema:
                type: object
                required:
                - verificationId
                - codes
                properties:
                  verificationId:
                    type: string
                    description: The unique verification ID of the newly created BackupCode verification record. This ID is required when adding the backup codes to the user profile via the Profile API.
                  codes:
                    type: array
                    items:
                      type: string
                    description: The generated backup codes.
        '400':
          description: Bad Request
        '404':
          description: The current interaction is not identified yet. All MFA verification records must be associated with a identified user.
      security: []
      summary: Generate backup codes
      description: Create a new BackupCode verification record with new backup codes generated. This verification record will be used to bind the backup codes to the user's profile.
  /api/experience/verification/backup-code/verify:
    post:
      operationId: VerifyBackupCode
      tags:
      - Experience
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - code
              properties:
                code:
                  type: string
                  minLength: 1
                  description: The backup code to verify.
      responses:
        '200':
          description: The backup code has been successfully verified.
          content:
            application/json:
              schema:
                type: object
                required:
                - verificationId
                properties:
                  verificationId:
                    type: string
                    description: The unique verification ID of the BackupCode verification record.
        '400':
          description: The provided backup code is invalid.
        '404':
          description: Entity not found. <br/> - `session.identifier_not_found:` The current interaction is not identified yet. All MFA verification records must be associated with a identified user.
      security: []
      summary: Verify backup code
      description: Create a new BackupCode verification record and verify the provided backup code against the user's backup codes. The verification record will be marked as verified if the code is correct.
  /api/experience/verification/new-password-identity:
    post:
      operationId: CreateNewPasswordIdentityVerification
      tags:
      - Experience
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - identifier
              - password
              properties:
                identifier:
                  type: object
                  required:
                  - type
                  - value
                  properties:
                    type:
                      type: string
                      format: '"username"'
                    value:
                      type: string
                      format: regex
                      pattern: /^[A-Z_a-z]\w*$/
                  description: The unique user identifier.  <br/> Currently, only `username` is accepted. For `email` or `phone` registration, a `CodeVerification` record must be created and used to verify the user's email or phone number identifier.
                password:
                  type: string
                  description: The new user password. (A password digest will be created and stored securely in the verification record.)
      responses:
        '200':
          description: The NewPasswordIdentity verification record has been successfully created.
          content:
            application/json:
              schema:
                type: object
                required:
                - verificationId
                properties:
                  verificationId:
                    type: string
                    description: The unique verification ID of the newly created NewPasswordIdentity verification record. The `verificationId` is required when creating a new user account via the `Identification` API.
        '400':
          description: Bad Request
        '422':
          description: Unable to process the request. <br/>- `user.username_already_in_use:` The provided username is already in use. <br/>- `password.rejected:` The provided password is rejected by the password policy. Detailed password violation information is included in the response.
      security: []
      summary: Create new password identity verification
      description: Create a NewPasswordIdentity verification record for the new user registration use. The verification record includes a unique user identifier and a password that can be used to create a new user account.
  /api/experience/verification/one-time-token/verify:
    post:
      operationId: VerifyOneTimeTokenVerification
      tags:
      - Experience
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - identifier
              - token
              properties:
                identifier:
                  type: object
                  required:
                  - type
                  - value
                  properties:
                    type:
                      type: string
                      format: '"email"'
                    value:
                      type: string
                      format: regex
                      pattern: /^\S+@\S+\.\S+$/
                  description: The unique user identifier.  <br/> Currently, only `email` is accepted.
                token:
                  type: string
                  minLength: 1
                  description: The one-time token to be verified.
      responses:
        '200':
          description: The one-time token was successfully verified.
          content:
            application/json:
              schema:
                type: object
                required:
                - verificationId
                properties:
                  verificationId:
                    type: string
                    description: The unique ID of the verification record. Required for user identification via the `Identification` API or to bind the identifier to the user's account via the `Profile` API.
        '400':
          description: The one-time token is invalid or the maximum number of attempts has been exceeded. Check the error message for details.
        '404':
          description: Verification record not found.
      security: []
      summary: Verify one-time token
      description: Verify the provided one-time token against the user's email. If successful, the verification record will be marked as verified.
  /api/experience/profile:
    post:
      operationId: AddUserProfile
      tags:
      - Experience
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - type: object
                required:
                - type
                - value
                properties:
                  type:
                    type: string
                    format: '"username"'
                  value:
                    type: string
                    format: regex
                    pattern: /^[A-Z_a-z]\w*$/
              - type: object
                required:
                - type
                - value
                properties:
                  type:
                    type: string
                    format: '"password"'
                  value:
                    type: string
              - type: object
                required:
                - type
                - verificationId
                properties:
                  type:
                    type: string
                    format: '"email"'
                  verificationId:
                    type: string
              - type: object
                required:
                - type
                - verificationId
                properties:
                  type:
                    type: string
                    format: '"phone"'
                  verificationId:
                    type: string
              - type: object
                required:
                - type
                - verificationId
                properties:
                  type:
                    type: string
                    format: '"social"'
                  verificationId:
                    type: string
              - type: object
                required:
                - type
                - values
                properties:
                  type:
                    type: string
                    format: '"extraProfile"'
                  values:
                    type: object
                    additionalProperties:
                      example: {}
              properties:
                type:
                  description: 'The type of profile data to add. Available options: `email`, `phone`, `username`, `password`, `social`, or `extraProfile`.'
                value:
                  description: The plain text value of the profile data. Only supported for profile data types that does not require verification, such as `username` and `password`.
                values:
                  description: The extra profile data to add. Only supported for `extraProfile` type. The data will be validated and split into standard user profile attributes and custom user profile attributes. The standard user profile attributes will be set to the user profile, whereas the custom user profile attributes will be set to the user custom data.
                verificationId:
                  description: The ID of the verification record used to verify the profile data. Required for profile data types that require verification, such as `email`, `phone` and `social`.
      responses:
        '204':
          description: The profile data has been successfully added to the current experience interaction.
        '400':
          description: 'Invalid request. <br/> - `session.not_supported_for_forgot_password:` This API can not be used in the `ForgotPassword` interaction. <br/>- `session.verification_failed:` The verification record is not verified. '
        '403':
          description: '`SignIn` interaction only: MFA is enabled for the user but has not been verified. The user must verify MFA before updating non-social profile data.'
        '404':
          description: Entity not found. <br/> - `session.identifier_not_found:` (`SignIn` interaction only) The current interaction is not identified yet. All profile data must be associated with a identified user. <br/>- `session.verification_session_not_found:` The verification record is not found.
        '422':
          description: The user profile can not been processed, check error message for more details. <br/>- The profile data is invalid or conflicts with existing user data. <br/>- The profile data is already in use by another user account. <br/>- The email address is enterprise SSO enabled, can only be linked through the SSO connector.
      security: []
      summary: Add user profile
      description: 'Adds user profile data to the current experience interaction. <br/>- For `Register`: The profile data provided before the identification request will be used to create a new user account. <br/>- For `SignIn` and `Register`: The profile data provided after the user is identified will be used to update the user''s profile when the interaction is submitted. <br/>- `ForgotPassword`: Not supported.'
  /api/experience/profile/password:
    put:
      operationId: ResetUserPassword
      tags:
      - Experience
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - password
              properties:
                password:
                  type: string
                  description: The new password to update. The password must meet the password policy requirements and can not be the same as the current password.
      responses:
        '204':
          description: The password has been successfully updated.
        '400':
          description: The current interaction event is not `ForgotPassword`. The password can only be updated through the `ForgotPassword` interaction.
        '404':
          description: The user has not been identified yet. The user must be identified before updating the password.
        '422':
          description: The password can not be updated due to validation errors, check error message for more details. <br/>- `user.password_policy_violation:` The password does not meet the password policy requirements. <br/>- `user.same_password:` The new password is the same as the current password.
      security: []
      summary: Reset user password
      description: Reset the user's password. (`ForgotPassword` interaction only)
  /api/experience/profile/mfa/mfa-enabled:
    post:
      operationId: MarkMfaEnabled
      tags:
      - Experience
      parameters: []
      responses:
        '204':
          description: The MFA has been successfully marked as enabled. This is typically useful for optional MFA scenarios as the client can prompt an MFA enrollment flow if the user has not enabled MFA yet, for added security.
        '400':
          description: Not supported for the current interaction event. The MFA profile API can only be used in the `SignIn` or `Register` interaction.
        '403':
          description: MFA verification is required but has not been completed. The user must verify the existing MFA before updating MFA settings.
        '404':
          description: The user has not been identified yet. The `mfa-enabled` configuration must be associated with an identified user.
      security: []
      summary: Mark MFA as enabled
      description: Mark the user's MFA as enabled for the current interaction and persist in DB user configs upon successful submission.
  /api/experience/profile/mfa/mfa-skipped:
    post:
      operationId: SkipMfaBindingFlow
      tags:
      - Experience
      parameters: []
      responses:
        '204':
          description: The MFA verification has been successfully skipped.
        '400':
          description: Not supported for the current interaction event. The MFA profile API can only be used in the `SignIn` or `Register` interaction.
        '403':
          description: Some MFA factors has already been enabled for the user. The user must verify the MFA before updating the MFA settings.
        '404':
          description: The user has not been identified yet. The `mfa-skipped` configuration must be associated with an identified user.
        '422':
          description: The MFA verification binding is `Mandatory`, user can not skip the MFA verification binding flow.
      security: []
      summary: Skip MFA binding flow
      description: Skip MFA verification binding flow. If the MFA is enabled in the sign-in experience settings and marked as `UserControlled`, the user can skip the MFA verification binding flow by calling this API.
  /api/experience/profile/mfa/mfa-suggestion-skipped:
    post:
      operationId: SkipMfaSuggestion
      tags:
      - Experience
      parameters: []
      responses:
        '204':
          description: The suggestion was successfully skipped.
        '400':
          description: Not supported for the current interaction event. The MFA profile API can only be used in the `SignIn` or `Register` interaction.
        '403':
          description: Some MFA factors have already been enabled for the user. The user must verify MFA before updating related settings.
        '404':
          description: The user has not been identified yet. The suggestion state must be associated with an identified user.
        '422':
          description: The suggestion is not skippable under current policy.
      security: []
      summary: Skip additional MFA suggestion
      description: Mark the optional additional MFA binding suggestion as skipped for the current interaction. When multiple MFA factors are enabled and only an email/phone factor is configured, a suggestion to add another factor may be shown; this endpoint records the choice to skip.
  /api/experience/profile/mfa/passkey-skipped:
    post:
      operationId: SkipPasskeyBinding
      tags:
      - Experience
      parameters: []
      responses:
        '204':
          description: The passkey binding flow has been permanently skipped.
        '400':
          description: Not supported for the current interaction event. This API can only be used in the `SignIn` or `Register` interaction.
        '404':
          description: The user has not been identified yet. The `passkey-skipped` configuration must be associated with a identified user.
      security: []
      summary: Skip passkey binding
      description: Skip passkey binding flow. The users can temporarily skip the passkey binding flow by calling this API during sign-up. On sign-in, the skip flag will be persisted to user config.
  /api/experience/profile/mfa/passkey:
    post:
      operationId: BindPasskey
      tags:
      - Experience
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - verificationId
              properties:
                verificationId:
                  type: string
                  description: The ID of the WebAuthn verification record to bind as a passkey.
      responses:
        '204':
          description: The passkey has been successfully bound to the user profile.
        '400':
          description: Invalid request. <br/>- `session.verification_failed:` The WebAuthn verification record is invalid or not verified. <br/>- `session.mfa.pending_info_not_found:` The verification record does not have the required registration data.
        '404':
          description: Entity not found. <br/>- `session.identifier_not_found:` The user has not been identified yet. <br/>- `session.verification_session_not_found:` The WebAuthn verification record is not found.
      security: []
      summary: Bind passkey for sign-in
      description: 'Bind a WebAuthn credential as a passkey for sign-in purposes. Unlike `POST /api/experience/profile/mfa` with `type: WebAuthn`, this endpoint is exclusively for adding a passkey as a sign-in method and does NOT mark the user''s optional MFA as enabled.'
  /api/experience/profile/mfa:
    post:
      operationId: BindMfaVerification
      tags:
      - Experience
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - type
              - verificationId
              properties:
                type:
                  type: string
                  enum:
                  - Totp
                  - WebAuthn
                  - BackupCode
                  - EmailVerificationCode
                  - PhoneVerificationCode
                  description: The type of MFA.
                verificationId:
                  type: string
                  description: The ID of the MFA verification record.
      responses:
        '204':
          description: The MFA verification has been successfully added to the user profile.
        '400':
          description: Invalid request. <br/>- `session.verification_failed:` The MFA verification record is invalid or not verified. <br/>- `session.mfa.mfa_factor_not_enabled:` The MFA factor is not enabled in the sign-in experience settings. <br/>- `session.mfa.pending_info_not_found:` The MFA verification record does not have the required information to bind the MFA verification.
        '403':
          description: Forbidden
        '404':
          description: Entity not found. <br/> - `session.identifier_not_found:` The user has not been identified yet. The MFA verification can only be added to a identified user. <br/>- `session.verification_session_not_found:` The MFA verification record is not found.
        '422':
          description: 'The MFA verification can not been processed, check error message for more details. <br/>- `user.totp_already_in_use`: A TOTP MFA secret is already in use in the current user profile. <br/>- `session.mfa.backup_code_can_not_be_alone`: The backup code can not be the only MFA factor in the user profile.'
      security: []
      summary: Bind MFA verification by verificationId
      description: Bind new MFA verification to the user profile using the verificationId.
  /api/experience/sso-connectors:
    get:
      operationId: GetEnabledSsoConnectors
      tags:
      - Experience
      parameters:
      - name: email
        in: query
        required: true
        schema:
          type: string
          format: email
        description: The email address to find the enabled SSO connectors.
      responses:
        '200':
          description: The enabled SSO connectors have been successfully retrieved.
          content:
            application/json:
              schema:
                type: object
                required:
                - connectorIds
                properties:
                  connectorIds:
                    type: array
                    items:
                      type: string
                    description: The list of enabled SSO connectorIds. Returns an empty array if no enabled SSO connectors are found.
        '400':
          description: The email address is invalid, can not extract a valid domain from it.
      security: []
      summary: Get enabled SSO connectors by the given email's domain
      description: Extract the email domain from the provided email address. Returns all the enabled SSO connectors that match the email domain.
  /api/experience/preflight/sign-in-passkey/authentication:
    post:
      operationId: CreateSignInPasskeyAuthentication
      tags:
      - Experience
      parameters: []
      responses:
        '200':
          description: Passkey sign-in WebAuthn authentication options have been successfully created.
          content:
            application/json:
              schema:
                type: object
                required:
                - authenticationOptions
                properties:
                  authenticationOptions:
                    type: object
                    required:
                    - challenge
                    properties:
                      challenge:
                        type: string
                      timeout:
                        type: number
                      rpId:
                        type: string
                      allowCredentials:
                        type: array
                        items:
                          type: object
                          required:
                          - type
                          - id
                          properties:
                            type:
                              type: string
                              format: '"public-key"'
                            id:
                              type: string
                            transports:
                              type: array
                              items:
                                type: string
                                enum:
                                - usb
                                - nfc
                                - ble
                                - internal
                                - cable
                                - hybrid
                                - smart-card
                      userVerification:
                        type: string
                        enum:
                        - required
                        - preferred
                        - discouraged
                      extensions:
                        type: object
                        properties:
                          appid:
                            type: string
                          credProps:
                            type: boolean
                          hmacCreateSecret:
                            type: boolean
                    description: The WebAuthn authentication options for initiating passkey sign-in.
        '400':
          description: Invalid request.
        '404':
          description: Verification session not found.
      security: []
      summary: Create passkey sign-in WebAuthn authentication
      description: Create WebAuthn authentication options for passkey sign-in. The user will be resolved later by the credential during verification.
components:
  parameters:
    connectorId:
      in: path
      description: The unique identifier of the connector.
      required: true
      schema:
        type: string
      name: connectorId
  securitySchemes:
    OAuth2:
      type: oauth2
      description: "Logto Management API is a comprehensive set of REST APIs that gives you the full control over Logto to suit your product needs and tech stack. To see the full guide on Management API interactions, visit [Interact with Management API](https://docs.logto.io/docs/recipes/interact-with-management-api/).\n\n### Get started\n\nThe API follows the same authentication principles as other API resources in Logto, with some slight differences. To use Logto Management API:\n\n1. A machine-to-machine (M2M) application needs to be created.\n2. A machine-to-machine (M2M) role with Management API permission `all` needs to be assigned to the application.\n\nOnce you have them set up, you can use the `client_credentials` grant type to fetch an access token and use it to authenticate your requests to the Logto Management API.\n\n### Fetch an access token\n\nTo fetch an access token, you need to make a `POST` request to the `/oidc/token` endpoint of your Logto tenant.\n\nFor Logto Cloud users, the base URL is your Logto endpoint, i.e. `https://[tenant-id].logto.app`. The tenant ID can be found in the following places:\n\n- The first path segment of the URL when you are signed in to Logto Cloud. For example, if the URL is `https://cloud.logto.io/foo/get-started`, the tenant ID is `foo`.\n- In the \"Settings\" tab of Logto Cloud.\n\nThe request should follow the OAuth 2.0 [client credentials](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4) grant type. Here is a non-normative example of how to fetch an access token:\n\n```bash\ncurl --location \\\n  --request POST 'https://[tenant-id].logto.app/oidc/token' \\\n  --header 'Content-Type: application/x-www-form-urlencoded' \\\n  --data-urlencode 'grant_type=client_credentials' \\\n  --data-urlencode 'client_id=[app-id]' \\\n  --data-urlencode 'client_secret=[app-secret]' \\\n  --data-urlencode 'resource=https://[tenant-id].logto.app/api' \\\n  --data-urlencode 'scope=all'\n```\n\nReplace `[tenant-id]`, `[app-id]`, and `[app-secret]` with your Logto tenant ID, application ID, and application secret, respectively.\n\nThe response will be like:\n\n```json\n{\n  \"access_token\": \"eyJhbG...2g\", // Use this value for accessing the Logto Management API\n  \"expires_in\": 3600, // Token expiration in seconds\n  \"token_type\": \"Bearer\", // Token type for your request when using the access token\n  \"scope\": \"all\" // Scope `all` for Logto Management API\n}\n```\n\n### Use the access token\n\nOnce you have the access token, you can use it to authenticate your requests to the Logto Management API. The access token should be included in the `Authorization` header of your requests with the `Bearer` authentication scheme.\n\nHere is an example of how to list the first page of users in your Logto tenant:\n\n```bash\ncurl --location \\\n  --request GET 'https://[tenant-id].logto.app/api/users' \\\n  --header 'Authorization: Bearer eyJhbG...2g'\n```\n\nReplace `[tenant-id]` with your Logto tenant ID and `eyJhbG...2g` with the access token you fetched earlier."
      flows:
        clientCredentials:
          tokenUrl: /oidc/token
          scopes:
            all: All scopes