Skip to main content

Account settings by account API

What is Logto Account API​

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

  • Direct access: The Account API empowers end users to directly access and manage their own account profile 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: Admin has full, global control over access settings, can customize each fields.
  • Seamless authorization: Authorizing 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>.

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

Some frequently usage are listed below:

  • Retrieve user profile
  • Update user profile
  • Update user password
  • Update user identities including email, phone, and social connections

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

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.

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 put the access token in the Authorization field of HTTP headers with the Bearer format (Bearer YOUR_TOKEN) when you're interacting with the Account API.

And 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 another layer of authorization for the 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.

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 PATCH 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 attach the verification record id to the request header with the logto-verification-id field.

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 PATCH 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 PATCH 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 PATCH /api/my-account/identities endpoint to link the social connection.

curl -X PATCH 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":"..."}'

Remove a social connection​

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