Logto My account API
Account routes provide functionality for managing user profile for the end user to interact directly with access tokens.
OpenAPI Specification
openapi: 3.0.1
info:
title: Logto API references Account center My account 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: My account
description: Account routes provide functionality for managing user profile for the end user to interact directly with access tokens.
paths:
/api/my-account:
get:
operationId: GetProfile
tags:
- My account
parameters: []
responses:
'200':
description: The profile was retrieved successfully.
content:
application/json:
schema:
type: object
properties:
id:
type: string
minLength: 1
maxLength: 12
username:
type: string
maxLength: 128
nullable: true
primaryEmail:
type: string
maxLength: 128
nullable: true
primaryPhone:
type: string
maxLength: 128
nullable: true
name:
type: string
maxLength: 128
nullable: true
avatar:
type: string
maxLength: 2048
nullable: true
customData:
type: object
description: arbitrary
identities:
type: object
additionalProperties:
type: object
required:
- userId
properties:
userId:
type: string
details:
type: object
description: arbitrary
lastSignInAt:
type: number
nullable: true
createdAt:
type: number
updatedAt:
type: number
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
applicationId:
type: string
maxLength: 21
nullable: true
isSuspended:
type: boolean
hasPassword:
type: boolean
ssoIdentities:
type: array
items:
type: object
required:
- tenantId
- id
- userId
- issuer
- identityId
- detail
- createdAt
- updatedAt
- ssoConnectorId
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 21
userId:
type: string
minLength: 1
maxLength: 12
issuer:
type: string
minLength: 1
maxLength: 256
identityId:
type: string
minLength: 1
maxLength: 128
detail:
type: object
description: arbitrary
createdAt:
type: number
updatedAt:
type: number
ssoConnectorId:
type: string
minLength: 1
maxLength: 128
'401':
description: Unauthorized
'403':
description: Forbidden
summary: Get profile
description: Get profile for the user.
patch:
operationId: UpdateProfile
tags:
- My account
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
nullable: true
description: The new name for the user.
avatar:
type: string
format: url
nullable: true
description: The new avatar for the user, must be a URL.
username:
type: string
format: regex
pattern: /^[A-Z_a-z]\w*$/
nullable: true
description: The new username for the user, must be a valid username and unique.
customData:
type: object
description: The new custom data for the user. This will completely replace the existing customData. Requires CustomData scope.
responses:
'200':
description: The profile was updated successfully.
content:
application/json:
schema:
type: object
properties:
id:
type: string
minLength: 1
maxLength: 12
username:
type: string
maxLength: 128
nullable: true
primaryEmail:
type: string
maxLength: 128
nullable: true
primaryPhone:
type: string
maxLength: 128
nullable: true
name:
type: string
maxLength: 128
nullable: true
avatar:
type: string
maxLength: 2048
nullable: true
customData:
type: object
description: arbitrary
identities:
type: object
additionalProperties:
type: object
required:
- userId
properties:
userId:
type: string
details:
type: object
description: arbitrary
lastSignInAt:
type: number
nullable: true
createdAt:
type: number
updatedAt:
type: number
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
applicationId:
type: string
maxLength: 21
nullable: true
isSuspended:
type: boolean
hasPassword:
type: boolean
ssoIdentities:
type: array
items:
type: object
required:
- tenantId
- id
- userId
- issuer
- identityId
- detail
- createdAt
- updatedAt
- ssoConnectorId
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 21
userId:
type: string
minLength: 1
maxLength: 12
issuer:
type: string
minLength: 1
maxLength: 256
identityId:
type: string
minLength: 1
maxLength: 128
detail:
type: object
description: arbitrary
createdAt:
type: number
updatedAt:
type: number
ssoConnectorId:
type: string
minLength: 1
maxLength: 128
'400':
description: The request body is invalid.
'401':
description: Permission denied, the verification record is invalid.
'403':
description: Forbidden
'422':
description: The username is already in use.
summary: Update profile
description: Update profile for the user, only the fields that are passed in will be updated. Updating or deleting username requires a logto-verification-id header for checking sensitive permissions. Removing any sign-in identifier, including username, is rejected if it would remove the user's last identifier.
/api/my-account/profile:
patch:
operationId: UpdateOtherProfile
tags:
- My account
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
familyName:
type: string
description: The new family name for the user.
givenName:
type: string
description: The new given name for the user.
middleName:
type: string
description: The new middle name for the user.
nickname:
type: string
description: The new nickname for the user.
preferredUsername:
type: string
description: The new preferred username for the user.
profile:
type: string
description: The new profile for the user.
website:
type: string
description: The new website for the user.
gender:
type: string
description: The new gender for the user.
birthdate:
type: string
description: The new birthdate for the user.
zoneinfo:
type: string
description: The new zoneinfo for the user.
locale:
type: string
description: The new locale for the user.
address:
type: object
properties:
formatted:
type: string
streetAddress:
type: string
locality:
type: string
region:
type: string
postalCode:
type: string
country:
type: string
description: The new address for the user.
responses:
'200':
description: The profile was updated successfully.
content:
application/json:
schema:
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
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
summary: Update other profile
description: Update other profile for the user, only the fields that are passed in will be updated, to update the address, the user must have the address scope.
/api/my-account/password:
post:
operationId: UpdatePassword
tags:
- My account
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- password
properties:
password:
type: string
minLength: 1
description: The new password for the user.
responses:
'204':
description: The password was updated successfully.
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Permission denied, the verification record is invalid.
'422':
description: Unprocessable Content
summary: Update password
description: Update password for the user, a logto-verification-id in header is required for checking sensitive permissions.
/api/my-account/mfa-settings:
get:
operationId: GetMfaSettings
tags:
- My account
parameters: []
responses:
'200':
description: The MFA settings were retrieved successfully.
content:
application/json:
schema:
type: object
required:
- skipMfaOnSignIn
properties:
skipMfaOnSignIn:
type: boolean
'400':
description: Bad Request
'401':
description: Permission denied, insufficient scope or MFA field not enabled.
'403':
description: Forbidden
summary: Get MFA settings
description: Get MFA settings for the user. This endpoint requires the Identities scope. Returns current MFA configuration preferences.
patch:
operationId: UpdateMfaSettings
tags:
- My account
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- skipMfaOnSignIn
properties:
skipMfaOnSignIn:
type: boolean
responses:
'200':
description: The MFA settings were updated successfully.
content:
application/json:
schema:
type: object
required:
- skipMfaOnSignIn
properties:
skipMfaOnSignIn:
type: boolean
'400':
description: The request body is invalid.
'401':
description: Permission denied, identity verification is required or insufficient scope.
'403':
description: Forbidden
summary: Update MFA settings
description: Update MFA settings for the user. This endpoint requires identity verification and the Identities scope. Controls whether MFA verification is required during sign-in when the user has MFA configured.
/api/my-account/logto-configs:
get:
operationId: GetLogtoConfig
tags:
- My account
parameters: []
responses:
'200':
description: The exposed logto config fields were retrieved successfully.
content:
application/json:
schema:
type: object
required:
- mfa
- passkeySignIn
properties:
mfa:
type: object
required:
- skipped
- skipMfaOnSignIn
properties:
enabled:
type: boolean
skipped:
type: boolean
skipMfaOnSignIn:
type: boolean
passkeySignIn:
type: object
required:
- skipped
properties:
skipped:
type: boolean
'400':
description: MFA is not available in the account center.
'401':
description: Permission denied due to insufficient scope.
'403':
description: Forbidden
summary: Get logto config
description: Retrieve the exposed portion of the current user's logto config. This includes MFA states (enabled, skipped, skipMfaOnSignIn) and passkey sign-in binding states (skipped). Passkey is a WebAuthn MFA factor and shares the same account center field access control as MFA.
patch:
operationId: UpdateLogtoConfig
tags:
- My account
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
mfa:
type: object
properties:
enabled:
type: boolean
description: Set whether MFA is enabled for the user.
skipped:
type: boolean
description: Set whether the user is marked as having skipped MFA binding.
additionalBindingSuggestionSkipped:
type: boolean
skipMfaOnSignIn:
type: boolean
description: Set whether the user has opted to skip MFA verification on sign-in. This is ignored when the MFA policy is mandatory.
passkeySignIn:
type: object
properties:
skipped:
type: boolean
description: Set whether the user has persistently skipped binding a passkey for sign-in.
responses:
'200':
description: The exposed logto_config fields were updated successfully.
content:
application/json:
schema:
type: object
required:
- mfa
- passkeySignIn
properties:
mfa:
type: object
required:
- skipped
- skipMfaOnSignIn
properties:
enabled:
type: boolean
skipped:
type: boolean
skipMfaOnSignIn:
type: boolean
passkeySignIn:
type: object
required:
- skipped
properties:
skipped:
type: boolean
'400':
description: The request body is invalid.
'401':
description: Permission denied due to insufficient scope.
'403':
description: Forbidden
summary: Update logto config
description: Update the exposed portion of the current user's logto config. Supports updating MFA states (enabled, skipped, skipMfaOnSignIn) and passkey sign-in binding states (skipped). Passkey is a WebAuthn MFA factor and shares the same account center field access control as MFA.
/api/my-account/identities/{target}/access-token:
get:
operationId: GetSocialIdentityAccessToken
tags:
- My account
parameters:
- name: target
in: path
required: true
schema:
type: string
minLength: 1
responses:
'200':
description: The access token was retrieved successfully.
content:
application/json:
schema:
type: object
required:
- access_token
properties:
access_token:
type: string
scope:
type: string
token_type:
type: string
expires_in:
oneOf:
- type: number
- type: string
'400':
description: Bad Request
'401':
description: Permission denied, the access_token is expired and the offline_access scope is not granted or expired.
'403':
description: Forbidden
'404':
description: The social identity does not exist or the access token is not available.
'422':
description: Unprocessable Content
summary: Retrieve the access token issued by a third-party social provider
description: "This API retrieves the access token issued by a third-party social provider for a given social target. \nAccess is only available if token storage is enabled for the corresponding social connector.\nWhen a user authenticates through a social provider, Logto automatically stores the provider’s tokens in an encrypted form.\nYou can use this API to securely retrieve the stored access token and use it to access third-party APIs on behalf of the user."
put:
operationId: UpdateSocialIdentityAccessTokenByVerificationId
tags:
- My account
parameters:
- name: target
in: path
required: true
schema:
type: string
minLength: 1
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- verificationRecordId
properties:
verificationRecordId:
type: string
minLength: 1
responses:
'200':
description: The token storage was updated successfully. The new access token is returned in the response body.
content:
application/json:
schema:
type: object
required:
- access_token
properties:
access_token:
type: string
scope:
type: string
token_type:
type: string
expires_in:
oneOf:
- type: number
- type: string
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'422':
description: The verification record is invalid; the social identity does not exist; or the access token is not available.
summary: Update the access token for a social identity by verification ID
description: "This API updates the token storage for a social identity by a given social verification ID. \nIt is used to fetch a new access token from the social provider and store it securely in Logto."
/api/my-account/sso-identities/{connectorId}/access-token:
get:
operationId: GetEnterpriseSsoIdentityAccessToken
tags:
- My account
parameters:
- $ref: '#/components/parameters/connectorId'
responses:
'200':
description: The access token was retrieved successfully.
content:
application/json:
schema:
type: object
required:
- access_token
properties:
access_token:
type: string
scope:
type: string
token_type:
type: string
expires_in:
oneOf:
- type: number
- type: string
'400':
description: Bad Request
'401':
description: Permission denied, the access_token is expired and the offline_access scope is not granted or expired.
'403':
description: Forbidden
'404':
description: The SSO connector does not exist or the access token is not available.
summary: Retrieve the access token issued by a third-party enterprise SSO provider
description: "This API retrieves the access token issued by a third-party enterprise SSO provider for a given SSO connector ID. \nAccess is only available if token storage is enabled for the corresponding connector.\nWhen a user authenticates through a SSO provider, Logto automatically stores the provider’s tokens in an encrypted form.\nYou can use this API to securely retrieve the stored access token and use it to access third-party APIs on behalf of the user."
/api/my-account/primary-email:
post:
operationId: UpdatePrimaryEmail
tags:
- My account
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- email
- newIdentifierVerificationRecordId
properties:
email:
type: string
format: regex
pattern: /^\S+@\S+\.\S+$/
description: The new email for the user.
newIdentifierVerificationRecordId:
type: string
description: The identifier verification record ID for the new email ownership verification.
responses:
'204':
description: The primary email was updated successfully.
'400':
description: The new verification record is invalid.
'401':
description: Unauthorized
'403':
description: Permission denied, the verification record is invalid.
'422':
description: Unprocessable Content
summary: Update primary email
description: Update primary email for the user, a logto-verification-id in header is required for checking sensitive permissions, and a new identifier verification record is required for the new email ownership verification.
delete:
operationId: DeletePrimaryEmail
tags:
- My account
parameters: []
responses:
'204':
description: The primary email was deleted successfully.
'400':
description: The request would remove the user's last identifier.
'401':
description: Permission denied, the verification record is invalid.
'403':
description: Forbidden
summary: Delete primary email
description: Delete primary email for the user, a logto-verification-id header is required for checking sensitive permissions. The request is rejected if it would remove the user's last identifier.
/api/my-account/primary-phone:
post:
operationId: UpdatePrimaryPhone
tags:
- My account
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- phone
- newIdentifierVerificationRecordId
properties:
phone:
type: string
format: regex
pattern: /^\d+$/
description: The new phone for the user.
newIdentifierVerificationRecordId:
type: string
description: The identifier verification record ID for the new phone ownership verification.
responses:
'204':
description: The primary phone was updated successfully.
'400':
description: The new verification record is invalid.
'401':
description: Unauthorized
'403':
description: Permission denied, the verification record is invalid.
'422':
description: Unprocessable Content
summary: Update primary phone
description: Update primary phone for the user,
# --- truncated at 32 KB (77 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/logto/refs/heads/main/openapi/logto-my-account-api-openapi.yml