--- openapi: 3.0.1 servers: - url: https://[tenant_id].logto.app/ description: Logto endpoint address. info: title: Logto experience API references description: |- API references for Logto experience interaction. 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 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 responses: '204': description: A new experience interaction has been successfully initiated. '400': description: Bad Request 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.
- `SignIn` and `ForgotPassword` interactions: Required to verify the user''s identity.
- `Register` interaction: Optional. If provided, it updates the profile data with the verification record before account creation. If omitted, the account is created using existing profile data in the current interaction.' linkSocialIdentity: type: boolean description: Applies to the SignIn interaction only, and is used when a SocialVerification type verificationId is provided.
- 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.
- If `false` or not provided, the API identifies the user solely through the social identity.
This parameters is used for linking a non-existing social identity to a related user account that can be identified through 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.
- `session.verification_failed:` The verification is not verified or can not be used to identify the user.
- `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.
- `session.verification_session_not_found:` The verification record is not found.
- `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).
- `user._already_in_use:` The given identifier is already in use by another user account.
- `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:
- `SignIn` and `ForgotPassword` interactions: Verifies the user''s identity using the provided `verificationId`.
- `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.
- The profile data is invalid or conflicts with existing user data.
- Required profile data is missing.
- The profile data is already in use by another user account. security: [] summary: Submit interaction description: Submit the current interaction.
- Submit the verified user identity to the OIDC provider for further authentication (SignIn and Register).
- Update the user's profile data if any (SignIn and Register).
- Reset the password and clear all the interaction records (ForgotPassword). "/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: type: object required: - type - value properties: type: type: string enum: - email - phone value: type: string 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 '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: VerifyVerificationCode tags: - Experience parameters: [] requestBody: required: true content: application/json: schema: type: object required: - identifier - verificationId - code properties: identifier: type: object required: - type - value properties: type: type: string enum: - email - phone value: type: string 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: he 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/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. 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.
- `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.
- `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.
- `session.mfa.pending_info_not_found:` The WebAuthn registration challenge is missing from the current verification record.
- `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.
- `session.mfa.pending_info_not_found:` The WebAuthn authentication challenge is missing in the current verification record.
- `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/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.
- `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.
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.
- `user.username_already_in_use:` The provided username is already in use.
- `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/profile": post: operationId: UpdateUserProfile 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 properties: type: description: The type of profile data to add. `email`, `phone`, `username`, `password`, etc. 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`. 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.
- `session.not_supported_for_forgot_password:` This API can not be used in the `ForgotPassword` interaction.
- `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 the MFA before updating the profile data." '404': description: Entity not found.
- `session.identifier_not_found:` (`SignIn` interaction only) The current interaction is not identified yet. All profile data must be associated with a identified user.
- `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.
- The profile data is invalid or conflicts with existing user data.
- The profile data is already in use by another user account. security: [] summary: Update user profile data description: 'Adds user profile data to the current experience interaction.
- For `Register`: The profile data provided before the identification request will be used to create a new user account.
- 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.
- `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.
- `user.password_policy_violation:` The password does not meet the password policy requirements.
- `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-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 a 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": 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 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.
- `session.verification_failed:` The MFA verification record is invalid or not verified.
- `session.mfa.mfa_factor_not_enabled:` The MFA factor is not enabled in the sign-in experience settings.
- `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.
- `session.identifier_not_found:` The user has not been identified yet. The MFA verification can only be added to a identified user.
- `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.
- `user.totp_already_in_use`: A TOTP MFA secret is already in use in the current user profile.
- `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/interaction": put: tags: - Interaction parameters: [] requestBody: required: true content: application/json: schema: type: object required: - event properties: event: type: string enum: - SignIn - Register - ForgotPassword identifier: oneOf: - type: object required: - username - password properties: username: type: string minLength: 1 password: type: string minLength: 1 - type: object required: - email - password properties: email: type: string minLength: 1 password: type: string minLength: 1 - type: object required: - phone - password properties: phone: type: string minLength: 1 password: type: string minLength: 1 - type: object required: - email - verificationCode properties: email: type: string format: regex pattern: "/^\\S+@\\S+\\.\\S+$/" verificationCode: type: string minLength: 1 - type: object required: - phone - verificationCode properties: phone: type: string format: regex pattern: "/^\\d+$/" verificationCode: type: string minLength: 1 - type: object required: - connectorId - connectorData properties: connectorId: type: string connectorData: type: object description: arbitrary - type: object required: - connectorId - email properties: connectorId: type: string email: type: string - type: object required: - connectorId - phone properties: connectorId: type: string phone: type: string profile: type: object properties: username: type: string format: regex pattern: "/^[A-Z_a-z]\\w*$/" email: type: string format: regex pattern: "/^\\S+@\\S+\\.\\S+$/" phone: type: string format: regex pattern: "/^\\d+$/" connectorId: type: string password: type: string responses: '204': description: No Content '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '422': description: Unprocessable Content security: [] delete: tags: - Interaction parameters: [] responses: '204': description: No Content '400': description: Bad Request security: [] "/api/interaction/event": put: tags: - Interaction parameters: [] requestBody: required: true content: application/json: schema: type: object required: - event properties: event: type: string enum: - SignIn - Register - ForgotPassword responses: '204': description: No Content '400': description: Bad Request '403': description: Forbidden '404': description: Not Found security: [] "/api/interaction/identifiers": patch: tags: - Interaction parameters: [] requestBody: required: true content: application/json: schema: oneOf: - type: object required: - username - password properties: username: type: string minLength: 1 password: type: string minLength: 1 - type: object required: - email - password properties: email: type: string minLength: 1 password: type: string minLength: 1 - type: object required: - phone - password properties: phone: type: string minLength: 1 password: type: string minLength: 1 - type: object required: - email - verificationCode properties: email: type: string format: regex pattern: "/^\\S+@\\S+\\.\\S+$/" verificationCode: type: string minLength: 1 - type: object required: - phone - verificationCode properties: phone: type: string format: regex pattern: "/^\\d+$/" verificationCode: type: string minLength: 1 - type: object required: - connectorId - connectorData properties: connectorId: type: string connectorData: type: object description: arbitrary - type: object required: - connectorId - email properties: connectorId: type: string email: type: string - type: object required: - connectorId - phone properties: connectorId: type: string phone: type: string responses: '204': description: No Content '400': description: Bad Request '401': description: Unauthorized '404': description: Not Found '422': description: Unprocessable Content security: [] "/api/interaction/profile": put: tags: - Interaction parameters: [] requestBody: required: true content: application/json: schema: type: object properties: username: type: string format: regex pattern: "/^[A-Z_a-z]\\w*$/" email: type: string format: regex pattern: "/^\\S+@\\S+\\.\\S+$/" phone: type: string format: regex pattern: "/^\\d+$/" connectorId: type: string password: type: string responses: '204': description: No Content '400': description: Bad Request '404': description: Not Found security: [] patch: tags: - Interaction parameters: [] requestBody: required: true content: application/json: schema: type: object properties: username: type: string format: regex pattern: "/^[A-Z_a-z]\\w*$/" email: type: string format: regex pattern: "/^\\S+@\\S+\\.\\S+$/" phone: type: string format: regex pattern: "/^\\d+$/" connectorId: type: string password: type: string responses: '204': description: No Content '400': description: Bad Request '404': description: Not Found security: [] delete: tags: - Interaction parameters: [] responses: '204': description: No Content '400': description: Bad Request '404': description: Not Found security: [] "/api/interaction/submit": post: tags: - Interaction parameters: [] responses: '200': description: OK content: application/json: schema: type: object required: - redirectTo properties: redirectTo: type: string '204': description: No Content '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '422': description: Unprocessable Content security: [] "/api/interaction/consent": post: tags: - Interaction parameters: [] requestBody: required: true content: application/json: schema: type: object properties: organizationIds: type: array items: type: string responses: '200': description: OK content: application/json: {} '400': description: Bad Request security: [] get: tags: - Interaction parameters: [] responses: '200': description: OK content: application/json: schema: type: object required: - application - user - redirectUri properties: application: type: object required: - id - name properties: id: type: string minLength: 1 maxLength: 21 name: type: string minLength: 1 maxLength: 256 branding: type: object properties: logoUrl: type: string format: url darkLogoUrl: type: string format: url favicon: type: string format: url darkFavicon: type: string format: url displayName: nullable: true type: string maxLength: 256 privacyPolicyUrl: nullable: true type: string maxLength: 2048 termsOfUseUrl: nullable: true type: string maxLength: 2048 user: type: object required: - id - name - avatar - username - primaryEmail - primaryPhone properties: id: type: string minLength: 1 maxLength: 12 name: nullable: true type: string maxLength: 128 avatar: nullable: true type: string maxLength: 2048 username: nullable: true type: string maxLength: 128 primaryEmail: nullable: true type: string maxLength: 128 primaryPhone: nullable: true type: string maxLength: 128 organizations: type: array items: type: object required: - id - name properties: id: type: string minLength: 1 maxLength: 21 name: type: string minLength: 1 maxLength: 128 missingResourceScopes: type: array items: type: object required: - resource - scopes properties: resource: type: object required: - name - indicator - id properties: name: type: string minLength: 1 indicator: type: string minLength: 1 id: type: string scopes: type: array items: type: object required: - id - name - description properties: id: type: string minLength: 1 maxLength: 21 name: type: string minLength: 1 maxLength: 256 description: nullable: true type: string missingOIDCScope: type: array items: type: string missingResourceScopes: type: array items: type: object required: - resource - scopes properties: resource: type: object required: - name - indicator - id properties: name: type: string minLength: 1 indicator: type: string minLength: 1 id: type: string scopes: type: array items: type: object required: - id - name - description properties: id: type: string minLength: 1 maxLength: 21 name: type: string minLength: 1 maxLength: 256 description: nullable: true type: string redirectUri: type: string security: [] "/api/interaction/verification/social-authorization-uri": post: tags: - Interaction parameters: [] requestBody: required: true content: application/json: schema: type: object required: - connectorId - state - redirectUri properties: connectorId: type: string state: type: string redirectUri: type: object description: Validator function responses: '200': description: OK content: application/json: schema: type: object required: - redirectTo properties: redirectTo: type: string '400': description: Bad Request '404': description: Not Found security: [] "/api/interaction/verification/verification-code": post: tags: - Interaction parameters: [] requestBody: required: true content: application/json: schema: oneOf: - type: object required: - email properties: email: type: string format: regex pattern: "/^\\S+@\\S+\\.\\S+$/" - type: object required: - phone properties: phone: type: string format: regex pattern: "/^\\d+$/" responses: '204': description: No Content '400': description: Bad Request '404': description: Not Found '501': description: Not Implemented security: [] "/api/interaction/verification/totp": post: tags: - Interaction parameters: [] responses: '200': description: OK content: application/json: schema: type: object required: - secret - secretQrCode properties: secret: type: string secretQrCode: type: string security: [] "/api/interaction/verification/webauthn-registration": post: tags: - Interaction parameters: [] responses: '200': description: OK content: application/json: schema: 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 security: [] "/api/interaction/verification/webauthn-authentication": post: tags: - Interaction parameters: [] responses: '200': description: OK content: application/json: schema: 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 '400': description: Bad Request security: [] "/api/interaction/bind-mfa": post: tags: - Interaction parameters: [] requestBody: required: true content: application/json: schema: oneOf: - type: object required: - type - code properties: type: type: string format: '"Totp"' code: type: string - 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 - type: object required: - type properties: type: type: string format: '"BackupCode"' responses: '204': description: No Content '400': description: Bad Request '401': description: Unauthorized '404': description: Not Found '422': description: Unprocessable Content security: [] "/api/interaction/mfa": put: tags: - Interaction parameters: [] requestBody: required: true content: application/json: schema: oneOf: - type: object required: - type - code properties: type: type: string format: '"Totp"' code: type: string - 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 - type: object required: - type - code properties: type: type: string format: '"BackupCode"' code: type: string responses: '204': description: No Content '400': description: Bad Request '422': description: Unprocessable Content security: [] "/api/interaction/mfa-skipped": put: tags: - Interaction parameters: [] requestBody: required: true content: application/json: schema: type: object required: - mfaSkipped properties: mfaSkipped: type: boolean format: 'true' responses: '204': description: No Content '400': description: Bad Request '422': description: Unprocessable Content security: [] "/api/interaction/single-sign-on/{connectorId}/authorization-url": post: tags: - Interaction parameters: - "$ref": "#/components/parameters/connectorId" requestBody: required: true content: application/json: schema: type: object required: - state - redirectUri properties: state: type: string minLength: 1 redirectUri: type: object description: Validator function responses: '200': description: OK content: application/json: schema: type: object required: - redirectTo properties: redirectTo: type: string '400': description: Bad Request '404': description: Not Found '500': description: Internal Server Error security: [] "/api/interaction/single-sign-on/{connectorId}/authentication": post: tags: - Interaction parameters: - "$ref": "#/components/parameters/connectorId" requestBody: required: true content: application/json: schema: type: object additionalProperties: example: {} responses: '200': description: OK content: application/json: schema: type: object required: - redirectTo properties: redirectTo: type: string '400': description: Bad Request '404': description: Not Found '422': description: Unprocessable Content '500': description: Internal Server Error security: [] "/api/interaction/single-sign-on/{connectorId}/registration": post: tags: - Interaction parameters: - "$ref": "#/components/parameters/connectorId" responses: '200': description: OK content: application/json: schema: type: object required: - redirectTo properties: redirectTo: type: string '400': description: Bad Request '403': description: Forbidden '404': description: Not Found '500': description: Internal Server Error security: [] "/api/interaction/single-sign-on/connectors": get: tags: - Interaction parameters: - name: email in: query required: true schema: type: string format: email responses: '200': description: OK content: application/json: schema: type: array items: type: string '400': description: Bad Request security: [] security: - cookieAuth: - all components: schemas: TranslationObject: type: object properties: "[translationKey]": "$ref": "#/components/schemas/Translation" example: input: username: Username password: Password action: sign_in: Sign In continue: Continue Translation: oneOf: - type: string securitySchemes: cookieAuth: type: apiKey in: cookie name: _interaction parameters: tenantId-root: name: id in: path description: The unique identifier of the tenant. required: true schema: type: string tenantId: name: tenantId in: path description: The unique identifier of the tenant. required: true schema: type: string connectorId-root: in: path description: The unique identifier of the connector. required: true schema: type: string name: id connectorId: in: path description: The unique identifier of the connector. required: true schema: type: string name: connectorId verificationId-root: in: path description: The unique identifier of the verification. required: true schema: type: string name: id verificationId: in: path description: The unique identifier of the verification. required: true schema: type: string name: verificationId tags: - name: Experience description: The Experience endpoints allow end-users to interact with Logto for identity verification and profile completion. - name: Interaction description: Interaction endpoints are used to manage and process interactions for end-users, such as sign-in experience. Interaction endpoints are legacy endpoints that are used internally, will be replaced with Experience endpoints instead.