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) に適切な権限 (Permissions) があることを保証するため、Logto 設定で対応するスコープ (Scopes) を正しく設定してください。

例えば、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 = {
  // ...他のオプション
  // ユースケースに合った適切なスコープ (Scopes) を追加してください。
  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 を使ってこれらの機能を実装できます。詳細は 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 へのアクセス方法

アクセストークン (Access token) の取得

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

公式 SDK を使わない場合は、アクセストークン (Access token) の発行リクエスト /oidc/token で resource を空に設定してください。

アクセストークン (Access token) を使って 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>'

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

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

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

レスポンス例：

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

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

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

基本的なアカウント情報には、ユーザー名、名前、アバター、プロファイルが含まれます。

ユーザー名・名前・アバターの更新は 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":"..."}'

プロファイルの更新は 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 の取得

まず、検証レコード ID を取得する必要があります。これは識別子の更新時にユーザーの本人確認に使われます。

検証レコード ID を取得するには、ユーザーのパスワードを検証するか、ユーザーのメールまたは電話に認証コードを送信します。

検証について詳しくは Account API によるセキュリティ認証を参照してください。

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

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 を使ってユーザーの識別子を更新できます。

検証レコード 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":"..."}'

コードの検証後、newIdentifierVerificationRecordId としてリクエストボディに verificationId を設定し、ユーザーのメールを更新できます。

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 エンドポイントでユーザーの電話番号を削除できます。

新しいソーシャル接続をリンクするには、まず認可 (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：ソーシャルコネクターの ID
redirectUri：ユーザーがアプリケーションを認可 (Authorization) した後のリダイレクト先 URI。この URL でコールバックを受け取るページをホストしてください。
state：ユーザーがアプリケーションを認可 (Authorization) した後に返される state。CSRF 攻撃防止用のランダム文字列です。

レスポンスに verificationRecordId が含まれるので、後で使用するために保持してください。

ユーザーがアプリケーションを認可 (Authorization) すると、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 は、ユーザーがアプリケーションを認可 (Authorization) した後にソーシャルコネクターから返されるデータです。コールバックページで 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 フィールドを有効化してください。

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

ブラウザのパスキーは特定のホスト名（RP ID）に紐づき、RP ID のオリジンのみがパスキーの登録・検証に利用できます。しかし、Account API へリクエストするフロントエンドアプリは Logto のサインインページとは異なるため、フロントエンドアプリのオリジンを関連オリジンリストに追加する必要があります。これにより、他の RP ID でもパスキーの登録・検証が可能になります。

デフォルトでは、Logto は RP ID をテナントドメインに設定します。たとえば、テナントドメインが https://example.logto.app の場合、RP ID は example.logto.app です。カスタムドメインを使う場合は、そのドメインが RP ID になります（例：https://auth.example.com なら RP ID は auth.example.com）。

フロントエンドアプリのオリジンが 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"]}'

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

ステップ 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": "..."
}

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

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

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

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

ステップ 3：パスキーの検証

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

ステップ 4：パスキーのリンク

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：パスキーのユーザーエージェント

パスキー名の更新：

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

パスキーの削除：

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 シークレットの生成

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:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=YourApp

ステップ 3：TOTP 要素のバインド

ユーザーが認証アプリにシークレットを追加した後、それを検証してアカウントにバインドします：

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：新しいバックアップコードの生成

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：バックアップコードをユーザーに表示

important:

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

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

コードはコピーしやすい形式で明確に表示し、ダウンロードオプション（テキストファイルや PDF など）も検討してください。

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

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 など）も有効化している必要があります。
各バックアップコードは一度しか使えません。

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

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 へのアクセス方法​

アクセストークン (Access token) の取得​

アクセストークン (Access token) を使って Account API へアクセス​

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

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

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

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

検証レコード ID の取得​

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

メールまたは電話に認証コードを送信して検証​

検証レコード ID を使ってリクエスト送信​

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

新しいメールの更新またはリンク​

ユーザーのメールの削除​

電話番号の管理​

新しいソーシャル接続のリンク​

ソーシャル接続の削除​

新しい WebAuthn パスキーのリンク​

既存 WebAuthn パスキーの管理​

新しい TOTP のリンク​

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

Logto Account API とは

Account API を有効化する方法

Account API へのアクセス方法

アクセストークン (Access token) の取得

アクセストークン (Access token) を使って Account API へアクセス

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

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

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

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

検証レコード ID の取得

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

メールまたは電話に認証コードを送信して検証

検証レコード ID を使ってリクエスト送信

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

新しいメールの更新またはリンク

ユーザーのメールの削除

電話番号の管理

新しいソーシャル接続のリンク

ソーシャル接続の削除

新しい WebAuthn パスキーのリンク

既存 WebAuthn パスキーの管理

新しい TOTP のリンク

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