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

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, and profile.

To update username, name, and avatar, 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 profile, 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. This can be used to verify the user's identity when updating identifiers.

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.

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

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.

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 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:

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 0: Add your front-end app origin to the related origins.

A passkey in Browser is linked to a specific hostname (RP ID), and only the origin of the RP ID can be used to register or verify a passkey. However, your front-end app which is sending the request to the Account API is not the same as Logto's sign-in page, so you need to add your front-end app origin to the related origins list. This will allow your front-end app to register and verify a passkey under other RP IDs.

By default, Logto will set the RP ID to the tenant domain, for example, if your tenant domain is https://example.logto.app, the RP ID will be example.logto.app. If you are using a custom domain, the RP ID will be the custom domain, for example, if your custom domain is https://auth.example.com, the RP ID will be auth.example.com.

Now, let's add your front-end app origin to the related origins, for example, if your front-end app origin is https://account.example.com:

curl -X PATCH https://[tenant-id].logto.app/api/webauthn-connectors \
  -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 1: request new registration options.

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 2: 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 3: verify the passkey.

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 4: finally, you can link the passkey.

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 passkey

To manage an existing WebAuthn passkey, 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:

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:

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.

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:

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:

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:

important:

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:

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:

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 passkey​

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 passkey

Link a new TOTP

Manage backup codes