アカウント設定 by Account API

Logto Account API とは

Logto Account API は、エンドユーザーが Management API を経由せずに直接 API アクセスできる包括的な API 群です。主な特徴は以下の通りです：

直接アクセス：Account API により、エンドユーザーは Management API の中継なしで自分のアカウントプロファイルへ直接アクセス・管理できます。
ユーザープロファイルとアイデンティティ管理：ユーザーは自分のプロファイルやセキュリティ設定を完全に管理でき、メール・電話・パスワードなどのアイデンティティ情報の更新やソーシャル連携の管理も可能です。多要素認証 (MFA) やシングルサインオン (SSO) のサポートも近日追加予定です。
グローバルアクセス制御：管理者はアクセス設定をグローバルに完全管理でき、各フィールドをカスタマイズできます。
シームレスな認可 (Authorization)：認可 (Authorization) がこれまで以上に簡単に！client.getAccessToken() を使って OP (Logto) 用の不透明トークン (Opaque token) を取得し、Authorization ヘッダーに Bearer <access_token> として付与するだけです。

注記:

アクセストークン (Access token) に適切な権限があることを保証するため、Logto の設定で対応するスコープ (Scope) を正しく設定してください。

例えば、POST /api/my-account/primary-email API には email スコープ (Scope) の設定が必要です。POST /api/my-account/primary-phone API には phone スコープ (Scope) の設定が必要です。

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

const config: LogtoConfig = {
  // ...他のオプション
  // 利用ケースに合った適切なスコープ (Scope) を追加してください。
  scopes: [
    UserScope.Email, // `{POST,DELETE} /api/my-account/primary-email` 用
    UserScope.Phone, // `{POST,DELETE} /api/my-account/primary-phone` 用
    UserScope.CustomData, // カスタムデータ管理用
    UserScope.Address, // 住所管理用
    UserScope.Identities, // アイデンティティや MFA 関連 API 用
    UserScope.Profile, // ユーザープロファイル管理用
  ],
};

Logto Account API を使えば、Logto と完全連携したプロフィールページのようなカスタムアカウント管理システムを構築できます。

よくあるユースケース例：

ユーザープロファイルの取得
ユーザープロファイルの更新
ユーザーパスワードの更新
メール・電話・ソーシャル連携などユーザーアイデンティティの更新
MFA 要素（認証要素）の管理

利用可能な API については Logto Account API Reference および Logto Verification API Reference をご覧ください。

注記:

以下の設定用の専用 Account API は近日公開予定です：SSO、カスタムデータ（ユーザー）、アカウント削除。それまでは Logto Management API を利用して実装できます。詳細は Account settings by Management API を参照してください。

MFA 管理 API（TOTP およびバックアップコード）は現在開発中で、isDevFeaturesEnabled フラグが true の場合のみ利用可能です。WebAuthn パスキー管理は完全に利用可能です。

Account API を有効化する方法

デフォルトでは、Account API は無効になっています。有効化するには Management API を使ってグローバル設定を更新する必要があります。

API エンドポイント /api/account-center でアカウントセンター設定の取得・更新ができます。これを使って Account API の有効 / 無効やフィールドのカスタマイズが可能です。

リクエスト例：

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

enabled フィールドで Account API の有効 / 無効を切り替え、fields フィールドで各フィールドのカスタマイズができます。値は Off、Edit、ReadOnly のいずれかです。デフォルトは Off です。フィールド一覧：

name：名前フィールド
avatar：アバターフィールド
profile：プロファイルフィールド（サブフィールド含む）
username：ユーザー名フィールド
email：メールフィールド
phone：電話フィールド
password：パスワードフィールド。取得時、ユーザーがパスワードを設定済みなら true、未設定なら false を返します。
social：ソーシャル連携
mfa：MFA 要素

API 詳細は Logto Management API Reference をご覧ください。

Account API へのアクセス方法

アクセストークンの取得

アプリケーションで SDK をセットアップした後、client.getAccessToken() メソッドでアクセストークン (Access token) を取得できます。このトークンは Account API へのアクセスに使える不透明トークン (Opaque token) です。

公式 SDK を使わない場合は、アクセストークン取得リクエスト /oidc/token の resource を空にしてください。

アクセストークンで Account API へアクセス

Account API へリクエストする際は、HTTP ヘッダーの Authorization フィールドに Bearer 形式（Bearer YOUR_TOKEN）でアクセストークン (Access token) を含めてください。

ユーザーアカウント情報を取得する例：

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

基本的なアカウント情報の管理

ユーザーアカウント情報の取得

ユーザーデータ取得には GET /api/my-account エンドポイントを利用します。

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

レスポンス例：

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

レスポンスのフィールドはアカウントセンター設定によって異なる場合があります。

基本アカウント情報の更新

基本アカウント情報にはユーザー名、名前、アバター、カスタムデータ、その他プロファイル情報が含まれます。

username, name, avatar, customData の更新には PATCH /api/my-account エンドポイントを利用します。

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

その他のプロファイル情報（familyName, givenName, middleName, nickname, profile（プロフィールページ URL）, website, gender, birthdate, zoneinfo, locale, address など）の更新には PATCH /api/my-account/profile エンドポイントを利用します。

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

識別子やその他の機微情報の管理

セキュリティ上、Account API で識別子や機微情報を扱う操作には追加の認可 (Authorization) 層が必要です。

検証レコード ID の取得

まず、10 分間有効な 検証レコード ID を取得する必要があります。これは機微情報の更新前にユーザーの本人確認を行うために使います。つまり、ユーザーがパスワード・メール認証コード・SMS 認証コードで本人確認に成功すると、10 分間は識別子・認証情報・ソーシャル連携・MFA などの認証関連データを更新できます。

検証レコード ID の取得方法は、ユーザーのパスワードで認証またはメール / 電話への認証コード送信です。

ユーザーのパスワードで認証

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

レスポンス例：

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

メールまたは電話への認証コード送信による認証

注記:

この方法を利用するにはメールコネクターの設定または SMS コネクターの設定を行い、UserPermissionValidation テンプレートが設定されていることを確認してください。

メールを例に、新しい認証コードをリクエストし検証レコード 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":"..."}}'

レスポンス例：

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

認証コードを受け取ったら、検証レコードの認証ステータスを更新できます。

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

コード認証後、検証レコード ID を使ってユーザーの識別子を更新できます。

認証について詳しくは Security verification by Account API を参照してください。

検証レコード ID を付与してリクエスト送信

ユーザーの識別子を更新するリクエストを送る際は、リクエストヘッダーの logto-verification-id フィールドに検証レコード ID を含めてください。

ユーザーパスワードの更新

ユーザーパスワードの更新には POST /api/my-account/password エンドポイントを利用します。

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

新しいメールの更新・連携

注記:

この方法を利用するにはメールコネクターの設定を行い、BindNewIdentifier テンプレートが設定されていることを確認してください。

新しいメールの更新・連携には、まずメールの所有権を証明する必要があります。

POST /api/verifications/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":"..."}}'

レスポンスに verificationId が含まれ、メールで認証コードが届きますので、それを使ってメール認証を行います。

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

コード認証後、PATCH /api/my-account/primary-email でユーザーのメールを更新できます。verificationId をリクエストボディの 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":"..."}'

ユーザーのメール削除

ユーザーのメール削除には DELETE /api/my-account/primary-email エンドポイントを利用します。

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

電話番号の管理

注記:

この方法を利用するには SMS コネクターの設定を行い、BindNewIdentifier テンプレートが設定されていることを確認してください。

メール更新と同様に、PATCH /api/my-account/primary-phone で新しい電話番号の更新・連携、DELETE /api/my-account/primary-phone で電話番号の削除ができます。

新しいソーシャル連携を追加するには、まず POST /api/verifications/social で認可 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：ソーシャルコネクターの ID
redirectUri：ユーザー認可後のリダイレクト先。ここでコールバックを受け取る Web ページをホストしてください。
state：認可後に返されるランダムな文字列（CSRF 対策）

レスポンスに verificationRecordId が含まれるので、後で利用します。

ユーザーが認可すると、redirectUri で state パラメータ付きのコールバックを受け取ります。その後、POST /api/verifications/social/verify でソーシャル連携を認証します。

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

connectorData はソーシャルコネクターから返されたデータで、コールバックページの redirectUri からクエリパラメータを取得し JSON 形式で connectorData フィールドに渡します。

最後に、POST /api/my-account/identities でソーシャル連携を追加します。

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

ソーシャル連携の削除には DELETE /api/my-account/identities エンドポイントを利用します。

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

新しい WebAuthn パスキーの追加

注記:

まず MFA および WebAuthn の有効化を行ってください。

注記:

この方法を利用するにはアカウントセンター設定で mfa フィールドを有効にしてください。

ステップ 1：フロントエンドアプリのオリジンを関連オリジンに追加

WebAuthn パスキーは Relying Party ID (RP ID) という特定のホスト名に紐づきます。RP ID のオリジンでホストされているアプリケーションのみ、そのパスキーで登録・認証できます。

フロントエンドアプリが Logto の認証ページとは異なるドメインから Account API を呼び出す場合、関連オリジン を設定してクロスオリジンのパスキー操作を許可する必要があります。

Logto が RP ID を決定する方法：

デフォルト：Logto のデフォルトドメイン https://[tenant-id].logto.app の場合、RP ID は [tenant-id].logto.app
カスタムドメイン：カスタムドメイン例：https://auth.example.com の場合、RP ID は auth.example.com

関連オリジンの設定方法：

PATCH /api/account-center エンドポイントでフロントエンドアプリのオリジンを追加します。例：アカウントセンターが 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"]}'

関連オリジンについて詳しくは Related Origin Requests ドキュメントを参照してください。

ステップ 2：新規登録オプションのリクエスト

POST /api/verifications/web-authn/registration エンドポイントで新しいパスキー登録をリクエストします。Logto では 1 アカウントにつき複数のパスキー登録が可能です。

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

レスポンス例：

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

ステップ 3：ローカルブラウザでパスキー登録

@simplewebauthn/browser を例に、startRegistration 関数でローカルブラウザにパスキーを登録します。

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

// ...
const response = await startRegistration({
  optionsJSON: registrationOptions, // ステップ 1 でサーバーから返されたデータ
});
// 後で利用するために response を保存

ステップ 4：パスキー登録の検証

POST /api/verifications/web-authn/registration/verify エンドポイントでパスキー登録を検証します。

このステップでは、認証器が生成した暗号署名を検証し、パスキーが正当に作成され転送中に改ざんされていないことを確認します。

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：ステップ 2 のローカルブラウザからのレスポンス
verificationRecordId：ステップ 1 でサーバーから返された検証レコード ID

ステップ 5：パスキーの連携

最後に、POST /api/my-account/mfa-verifications エンドポイントでパスキーをユーザーアカウントに連携します。

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：既存要素の認証で付与された有効な検証レコード ID。詳細は検証レコード ID の取得を参照。
type：MFA 要素のタイプ。現在は WebAuthn のみサポート。
newIdentifierVerificationRecordId：ステップ 1 でサーバーから返された検証レコード ID

既存 WebAuthn パスキーの管理

既存の WebAuthn パスキー管理には GET /api/my-account/mfa-verifications エンドポイントで現在のパスキーや他の MFA 要素を取得できます。

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

レスポンス例：

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

id：認証要素の ID
type：認証要素のタイプ。WebAuthn パスキーの場合は WebAuthn
name：パスキー名（任意）
agent：パスキーのユーザーエージェント

パスキー名の更新は PATCH /api/my-account/mfa-verifications/{verificationId}/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 /api/my-account/mfa-verifications/{verificationId} エンドポイントで行います：

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

新しい TOTP の連携

注記:

まず MFA および TOTP の有効化を行ってください。

注記:

この方法を利用するにはアカウントセンター設定で mfa フィールドを有効にしてください。

ステップ 1：TOTP シークレットの生成

POST /api/my-account/mfa-verifications/totp-secret/generate エンドポイントで TOTP シークレットを生成します。

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'

レスポンス例：

{
  "secret": "..."
}

ステップ 2：TOTP シークレットをユーザーに表示

シークレットを使って QR コードを生成するか、直接ユーザーに表示します。ユーザーはこれを Google Authenticator、Microsoft Authenticator、Authy などの認証アプリに追加します。

QR コード用 URI 形式：

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

例：

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

ステップ 3：TOTP 要素の連携

ユーザーが認証アプリにシークレットを追加したら、検証してアカウントに連携します。POST /api/my-account/mfa-verifications エンドポイントを利用します。

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：既存要素の認証で付与された有効な検証レコード ID。詳細は検証レコード ID の取得を参照。
type：Totp 固定
secret：ステップ 1 で生成した TOTP シークレット

注記:

ユーザーは TOTP 要素を 1 つしか持てません。すでに TOTP 要素がある場合、追加しようとすると 422 エラーになります。

バックアップコードの管理

注記:

まず MFA およびバックアップコードの有効化を行ってください。

注記:

この方法を利用するにはアカウントセンター設定で mfa フィールドを有効にしてください。

ステップ 1：新しいバックアップコードの生成

POST /api/my-account/mfa-verifications/backup-codes/generate エンドポイントで新しい 10 個のバックアップコードを生成します。

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'

レスポンス例：

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

ステップ 2：バックアップコードをユーザーに表示

バックアップコードをユーザーアカウントに連携する前に、必ずユーザーに表示し、以下を伝えてください：

すぐにダウンロードまたは書き留めること
安全な場所に保管すること
各コードは 1 回しか使えないこと
主要な MFA 手段を失った場合の最後の手段であること

コピーしやすい形式で表示し、ダウンロード（テキストファイルや PDF など）も推奨します。

ステップ 3：バックアップコードをユーザーアカウントに連携

POST /api/my-account/mfa-verifications エンドポイントでバックアップコードを連携します。

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：既存要素の認証で付与された有効な検証レコード ID。詳細は検証レコード ID の取得を参照。
type：BackupCode 固定
codes：前ステップで生成したバックアップコード配列

注記:

ユーザーは 1 セットのバックアップコードしか持てません。すべて使い切った場合は新たに生成・連携が必要です。
バックアップコードだけを MFA 要素にすることはできません。必ず他の MFA 要素（WebAuthn や TOTP など）が有効である必要があります。
各バックアップコードは 1 回しか使えません。

既存バックアップコードの確認

既存のバックアップコードと利用状況は GET /api/my-account/mfa-verifications/backup-codes エンドポイントで確認できます：

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

レスポンス例：

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

code：バックアップコード
usedAt：コードが使用された日時。未使用の場合は null

Logto Account API とは​

Account API を有効化する方法​

Account API へのアクセス方法​

アクセストークンの取得​

アクセストークンで Account API へアクセス​

基本的なアカウント情報の管理​

ユーザーアカウント情報の取得​

基本アカウント情報の更新​

識別子やその他の機微情報の管理​

検証レコード ID の取得​

ユーザーのパスワードで認証​

メールまたは電話への認証コード送信による認証​

検証レコード ID を付与してリクエスト送信​

ユーザーパスワードの更新​

新しいメールの更新・連携​

ユーザーのメール削除​

電話番号の管理​

新しいソーシャル連携の追加​

ソーシャル連携の削除​

新しい WebAuthn パスキーの追加​

既存 WebAuthn パスキーの管理​

新しい TOTP の連携​

バックアップコードの管理​

Logto Account API とは

Account API を有効化する方法

Account API へのアクセス方法

アクセストークンの取得

アクセストークンで Account API へアクセス

基本的なアカウント情報の管理

ユーザーアカウント情報の取得

基本アカウント情報の更新

識別子やその他の機微情報の管理

検証レコード ID の取得

ユーザーのパスワードで認証

メールまたは電話への認証コード送信による認証

検証レコード ID を付与してリクエスト送信

ユーザーパスワードの更新

新しいメールの更新・連携

ユーザーのメール削除

電話番号の管理

新しいソーシャル連携の追加

ソーシャル連携の削除

新しい WebAuthn パスキーの追加

既存 WebAuthn パスキーの管理

新しい TOTP の連携

バックアップコードの管理