Logto Experience API

Identify user for the current interaction

POST /api/experience/identification

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.

application/json

Body Required

  • verificationId string

    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 boolean

    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 application/json

    Register interaction: The user account has been successfully created and identified.

  • 204

    SignIn and ForgotPassword interactions: The user has been successfully identified.

  • 400

    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

    The user is suspended or banned from the service. (SignIn and ForgotPassword only)

  • 403

    The SignIn or Register interaction is disabled in the experience settings.

  • 404

    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

    The interaction has already been identified with a different user account.

  • 422

    The user account cannot be created due to validation errors, check error message for more details (Register only).
    - user.<identifier>_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)

POST /api/experience/identification 
curl \
 --request POST 'https://[tenant_id].logto.app/api/experience/identification' \
 --header "Content-Type: application/json" \
 --data '{"verificationId":"string","linkSocialIdentity":true}'
Request examples 
{
  "verificationId": "string",
  "linkSocialIdentity": true
}