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.
    - For SignIn and ForgotPassword interactions: Required to verify the user's identity.
    - 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 boolean

    Applies only to the SignIn interaction and is used when a SocialVerification type verification ID 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 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 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
}