Logto Experience API
The Experience endpoints allow end-users to interact with Logto for identity verification and profile completion.
OpenAPI Specification
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:
t
# --- truncated at 32 KB (108 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/logto/refs/heads/main/openapi/logto-experience-api-openapi.yml