Account settings by Account API

What is Logto Account API

The Logto Account API is a comprehensive set of APIs that gives end users direct API access without needing to go through the Management API. Here are the highlights:

Direct access: The Account API empowers end users to directly access and manage their own account profiles without requiring the relay of Management API.
User profile and identities management: Users can fully manage their profiles and security settings, including the ability to update identity information like email, phone, and password, as well as manage social connections. MFA and SSO support are coming soon.
Global access control: Admins have full, global control over access settings and can customize each field.
Seamless authorization: Authorization is easier than ever! Simply use client.getAccessToken() to obtain an opaque access token for OP (Logto), and attach it to the Authorization header as Bearer <access_token>.

note:

To ensure the access token has the appropriate permissions, make sure you have properly configured the corresponding scopes in your Logto config.

For example, for the POST /api/my-account/primary-email API, you need to configure the email scope; for the POST /api/my-account/primary-phone API, you need to configure the phone scope.

import { type LogtoConfig, UserScope } from '@logto/js';

const config: LogtoConfig = {
  // ...other options
  // Add proper scopes that fit your use cases.
  scopes: [
    UserScope.Email, // For `{POST,DELETE} /api/my-account/primary-email` APIs
    UserScope.Phone, // For `{POST,DELETE} /api/my-account/primary-phone` APIs
    UserScope.CustomData, // To manage custom data
    UserScope.Address, // To manage address
    UserScope.Identities, // For identity and MFA related APIs
    UserScope.Profile, // To manage user profile
  ],
};

With the Logto Account API, you can build a custom account management system like a profile page that is fully integrated with Logto.

Some frequent use cases are listed below:

Retrieve user profile
Update user profile
Update user password
Update user identities including email, phone, and social connections
Manage MFA factors (verifications)

To learn more about the available APIs, please visit Logto Account API Reference and Logto Verification API Reference.

note:

Dedicated Account APIs for the following settings are coming soon: SSO, Custom data (user), and Account deletion. In the meantime, you can implement these features using the Logto Management APIs. See Account settings by Management API for more details.

MFA management APIs (TOTP and backup codes) are currently under development and only available when the isDevFeaturesEnabled flag is set to true. WebAuthn passkey management is fully available.

How to enable Account API

By default, the Account API is disabled. To enable it, you need to use the Management API to update the global settings.

The API endpoint /api/account-center can be used to retrieve and update the account center settings. You can use it to enable or disable the Account API and customize the fields.

Example request:

curl -X PATCH https://[tenant-id].logto.app/api/account-center \
  -H 'authorization: Bearer <access_token for Logto Management API>' \
  -H 'content-type: application/json' \
  --data-raw '{"enabled":true,"fields":{"username":"Edit"}}'

The enabled field is used to enable or disable the Account API, and the fields field is used to customize the fields, the value can be Off, Edit, ReadOnly. The default value is Off. The list of fields:

name: The name field.
avatar: The avatar field.
profile: The profile field, including its sub fields.
username: The username field.
email: The email field.
phone: The phone field.
password: The password field, when getting, it will return true if the user has set a password, otherwise false.
social: Social connections.
mfa: MFA factors.

Learn more about the API details in Logto Management API Reference.

How to access Account API

Fetch an access token

After setting up the SDK in your application, you can use the client.getAccessToken() method to fetch an access token. This token is an opaque token that can be used to access the Account API.

If you are not using the official SDK, you should set the resource to empty for the access token grant request to /oidc/token.

Access Account API using access token

You should include the access token in the Authorization field of HTTP headers with the Bearer format (Bearer YOUR_TOKEN) when interacting with the Account API.

Here's an example to get the user account information:

curl https://[tenant-id].logto.app/api/my-account \
  -H 'authorization: Bearer <access_token>'

Manage basic account information

Retrieve user account information

To get user data, you can use the GET /api/my-account endpoint.

curl https://[tenant-id].logto.app/api/my-account \
  -H 'authorization: Bearer <access_token>'

The response body would be like:

{
  "id": "...",
  "username": "...",
  "name": "...",
  "avatar": "..."
}

The response fields may vary depending on the account center settings.

Update basic account information

Basic account information includes the username, name, avatar, custom data, and other profile information.

To update username, name, avatar, and customData you can use the PATCH /api/my-account endpoint.

curl -X PATCH https://[tenant-id].logto.app/api/my-account \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"username":"...","name":"...","avatar":"..."}'

To update other profile information, including familyName, givenName, middleName, nickname, profile (profile page URL), website, gender, birthdate, zoneinfo, locale, and address, you can use the PATCH /api/my-account/profile endpoint.

curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"familyName":"...","givenName":"..."}'

Manage identifiers and other sensitive information

For security reasons, the Account API requires an additional layer of authorization for operations that involve identifiers and other sensitive information.

Get a verification record id

First, you need to get a verification record ID with a 10-minute expiration (TTL). This can be used to verify the user's identity before updating sensitive information. This means once a user successfully verifies their identity via password, email verification code, or SMS verification code, they have 10 minutes to update their authentication-related data, including identifiers, credentials, social account linking, and MFA.

To get a verification record ID, you can verify the user's password or send a verification code to the user's email or phone.

Verify the user's password

curl -X POST https://[tenant-id].logto.app/api/verifications/password \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"password":"..."}'

The response body would be like:

{
  "verificationRecordId": "...",
  "expiresAt": "..."
}

Verify by sending a verification code to the user's email or phone

note:

To use this method, you need to configure the email connector or SMS connector, and make sure the UserPermissionValidation template is configured.

Take email as an example, request a new verification code and get the verification record ID:

curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"identifier":{"type":"email","value":"..."}}'

The response body would be like:

{
  "verificationRecordId": "...",
  "expiresAt": "..."
}

Upon receiving the verification code, you can use it to update the verification status of the verification record.

curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"123456"}'

After verifying the code, you can now use the verification record ID to update the user's identifier.

To learn more about verifications, please refer to Security verification by Account API.

Send request with verification record id

When sending a request to update the user's identifier, you need to include the verification record ID in the request header with the logto-verification-id field.

Update user's password

To update the user's password, you can use the POST /api/my-account/password endpoint.

curl -X POST https://[tenant-id].logto.app/api/my-account/password \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"password":"..."}'

Update or link new email

note:

To use this method, you need to configure the email connector, and make sure the BindNewIdentifier template is configured.

To update or link a new email, you should first prove the ownership of the email.

Call the POST /api/verifications/verification-code endpoint to request a verification code.

curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"identifier":{"type":"email","value":"..."}}'

You will find a verificationId in the response, and receive a verification code in the email, use it to verify the email.

curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"..."}'

After verifying the code, you can now call PATCH /api/my-account/primary-email to update the user's email, set the verificationId to the request body as newIdentifierVerificationRecordId.

curl -X POST https://[tenant-id].logto.app/api/my-account/primary-email \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"email":"...","newIdentifierVerificationRecordId":"..."}'

Remove the user's email

To remove the user's email, you can use the DELETE /api/my-account/primary-email endpoint.

curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>'

Manage phone

note:

To use this method, you need to configure the SMS connector, and make sure the BindNewIdentifier template is configured.

Similar to updating email, you can use the PATCH /api/my-account/primary-phone endpoint to update or link a new phone. And use the DELETE /api/my-account/primary-phone endpoint to remove the user's phone.

To link a new social connection, first you should request an authorization URL with POST /api/verifications/social.

curl -X POST https://[tenant-id].logto.app/api/verifications/social \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"connectorId":"...","redirectUri":"...","state":"..."}'

connectorId: The ID of the social connector.
redirectUri: The redirect URI after the user authorizes the application, you should host a web page at this URL and capture the callback.
state: The state to be returned after the user authorizes the application, it is a random string that is used to prevent CSRF attacks.

In the response, you will find a verificationRecordId, keep it for later use.

After the user authorizes the application, you will receive a callback at the redirectUri with the state parameter. Then you can use the POST /api/verifications/social/verify endpoint to verify the social connection.

curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"connectorData":"...","verificationRecordId":"..."}'

The connectorData is the data returned by the social connector after the user authorizes the application, you need to parse and get the query parameters from the redirectUri in your callback page, and wrap them as a JSON as the value of the connectorData field.

Finally, you can use the POST /api/my-account/identities endpoint to link the social connection.

curl -X POST https://[tenant-id].logto.app/api/my-account/identities \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"newIdentifierVerificationRecordId":"..."}'

To remove a social connection, you can use the DELETE /api/my-account/identities endpoint.

curl -X DELETE https://[tenant-id].logto.app/api/my-account/identities/[connector_target_id] \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>'

Link a new WebAuthn passkey

note:

Remember to enable MFA and WebAuthn first.

note:

To use this method, you need to enable the mfa field in the account center settings.

Step 1: Add your front-end app origin to the related origins

WebAuthn passkeys are bound to a specific hostname called the Relying Party ID (RP ID). Only applications hosted on the RP ID's origin can register or authenticate with those passkeys.

Since your front-end application calls the Account API from a different domain than Logto's authentication pages, you need to configure Related Origins to allow cross-origin passkey operations.

How Logto determines the RP ID:

Default setup: If you only use Logto's default domain https://[tenant-id].logto.app, the RP ID is [tenant-id].logto.app
Custom domain: If you've configured a custom domain like https://auth.example.com, the RP ID becomes auth.example.com

Configure Related Origins:

Use the PATCH /api/account-center endpoint to add your front-end application's origin. For example, if your app's account center runs on https://account.example.com:

curl -X PATCH https://[tenant-id].logto.app/api/account-center \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"webauthnRelatedOrigins":["https://account.example.com"]}'

To learn more about the related origins, please refer to Related Origin Requests documentation.

Step 2: Request new registration options

Use the POST /api/verifications/web-authn/registration endpoint to request registration for a new passkey. Logto allows each user account to register multiple passkeys.

curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json'

You'll get a response like:

{
  "registrationOptions": "...",
  "verificationRecordId": "...",
  "expiresAt": "..."
}

Step 3: Register the passkey in local browser

Take @simplewebauthn/browser as an example, you can use the startRegistration function to register the passkey in local browser.

import { startRegistration } from '@simplewebauthn/browser';

// ...
const response = await startRegistration({
  optionsJSON: registrationOptions, // The data returned by the server in step 1
});
// Save the response for later use

Step 4: Verify the passkey registration

Use the POST /api/verifications/web-authn/registration/verify endpoint to verify the passkey registration.

This step verifies the cryptographic signature generated by the authenticator to ensure the passkey was legitimately created and hasn't been tampered with during transmission.

curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration/verify \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"payload":"...","verificationRecordId":"..."}'

payload: The response from the local browser in step 2.
verificationRecordId: The verification record ID returned by the server in step 1.

Step 5: Link the passkey

Finally, you can link the passkey to the user's account using the POST /api/my-account/mfa-verifications endpoint.

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"type":"WebAuthn","newIdentifierVerificationRecordId":"..."}'

verification_record_id: a valid verification record ID, granted by verifying the user's existing factor, you can refer to the Get a verification record ID section for more details.
type: the type of the MFA factor, currently only WebAuthn is supported.
newIdentifierVerificationRecordId: the verification record ID returned by the server in step 1.

Manage existing WebAuthn passkeys

To manage existing WebAuthn passkeys, you can use the GET /api/my-account/mfa-verifications endpoint to get current passkeys and other MFA verification factors.

curl https://[tenant-id].logto.app/api/my-account/mfa-verifications \
  -H 'authorization: Bearer <access_token>'

The response body would be like:

[
  {
    "id": "...",
    "type": "WebAuthn",
    "name": "...",
    "agent": "...",
    "createdAt": "...",
    "updatedAt": "..."
  }
]

id: the ID of the verification.
type: the type of the verification, WebAuthn for WebAuthn passkey.
name: the name of the passkey, optional field.
agent: the user agent of the passkey.

Update the passkey name using PATCH /api/my-account/mfa-verifications/{verificationId}/name endpoint:

curl -X PATCH https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId}/name \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"name":"..."}'

Delete the passkey using DELETE /api/my-account/mfa-verifications/{verificationId} endpoint:

curl -X DELETE https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId} \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>'

Link a new TOTP

note:

Remember to enable MFA and TOTP first.

note:

To use this method, you need to enable the mfa field in the account center settings.

Step 1: Generate a TOTP secret

Use the POST /api/my-account/mfa-verifications/totp-secret/generate endpoint to generate a TOTP secret.

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp-secret/generate \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json'

The response body would be like:

{
  "secret": "..."
}

Step 2: Display the TOTP secret to the user

Use the secret to generate a QR code or display it directly to the user. The user should add it to their authenticator app (such as Google Authenticator, Microsoft Authenticator, or Authy).

The URI format for the QR code should be:

otpauth://totp/[Issuer]:[Account]?secret=[Secret]&issuer=[Issuer]

Example:

otpauth://totp/YourApp:[email protected]?secret=JBSWY3DPEHPK3PXP&issuer=YourApp

Step 3: Bind the TOTP factor

After the user has added the secret to their authenticator app, they need to verify it and bind it to their account. Use the POST /api/my-account/mfa-verifications endpoint to bind the TOTP factor.

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"type":"Totp","secret":"..."}'

verification_record_id: a valid verification record ID, granted by verifying the user's existing factor. You can refer to the Get a verification record ID section for more details.
type: must be Totp.
secret: the TOTP secret generated in step 1.

note:

A user can only have one TOTP factor at a time. If the user already has a TOTP factor, attempting to add another one will result in a 422 error.

Manage backup codes

note:

Remember to enable MFA and backup codes first.

note:

To use this method, you need to enable the mfa field in the account center settings.

Step 1: Generate new backup codes

Use the POST /api/my-account/mfa-verifications/backup-codes/generate endpoint to generate a new set of 10 backup codes.

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes/generate \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json'

The response body would be like:

{
  "codes": ["...", "...", "..."]
}

Step 2: Display backup codes to the user

Before binding the backup codes to the user's account, you must display them to the user and instruct them to:

Download or write down these codes immediately
Store them in a secure location
Understand that each code can only be used once
Know that these codes are their last resort if they lose access to their primary MFA methods

You should display the codes in a clear, easy-to-copy format and consider providing a download option (e.g., as a text file or PDF).

Step 3: Bind backup codes to the user account

Use the POST /api/my-account/mfa-verifications endpoint to bind the backup codes to the user's account.

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"type":"BackupCode","codes":["...","...","..."]}'

verification_record_id: a valid verification record ID, granted by verifying the user's existing factor. You can refer to the Get a verification record ID section for more details.
type: must be BackupCode.
codes: the array of backup codes generated in the previous step.

note:

A user can only have one set of backup codes at a time. If all codes have been used, the user needs to generate and bind new codes.
Backup codes cannot be the only MFA factor. The user must have at least one other MFA factor (such as WebAuthn or TOTP) enabled.
Each backup code can only be used once.

View existing backup codes

To view existing backup codes and their usage status, use the GET /api/my-account/mfa-verifications/backup-codes endpoint:

curl https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes \
  -H 'authorization: Bearer <access_token>'

The response body would be like:

{
  "codes": [
    {
      "code": "...",
      "usedAt": null
    },
    {
      "code": "...",
      "usedAt": "2024-01-15T10:30:00.000Z"
    }
  ]
}

code: the backup code.
usedAt: the timestamp when the code was used, null if not used yet.

What is Logto Account API​

How to enable Account API​

How to access Account API​

Fetch an access token​

Access Account API using access token​

Manage basic account information​

Retrieve user account information​

Update basic account information​

Manage identifiers and other sensitive information​

Get a verification record id​

Verify the user's password​

Verify by sending a verification code to the user's email or phone​

Send request with verification record id​

Update user's password​

Update or link new email​

Remove the user's email​

Manage phone​

Link a new social connection​

Remove a social connection​

Link a new WebAuthn passkey​

Manage existing WebAuthn passkeys​

Link a new TOTP​

Manage backup codes​

What is Logto Account API

How to enable Account API

How to access Account API

Fetch an access token

Access Account API using access token

Manage basic account information

Retrieve user account information

Update basic account information

Manage identifiers and other sensitive information

Get a verification record id

Verify the user's password

Verify by sending a verification code to the user's email or phone

Send request with verification record id

Update user's password

Update or link new email

Remove the user's email

Manage phone

Link a new social connection

Remove a social connection

Link a new WebAuthn passkey

Manage existing WebAuthn passkeys

Link a new TOTP

Manage backup codes