アカウント設定（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> として付与するだけです。

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

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

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

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

注記:

SSO アカウントの閲覧やアカウント削除機能は現在 Logto Management API で提供されています。実装の詳細は Management API によるアカウント設定 を参照してください。

Account API の有効化方法

コンソール > サインイン & アカウント > アカウントセンター

に移動します。

Account API はデフォルトでオフになっているため、アクセス制御はロックされています。Account API を有効化 を切り替えてオンにしてください。

有効化後は、識別子、プロファイルデータ、サードパーティトークンアクセスごとにフィールド単位で権限を設定できます。各フィールドは Off、ReadOnly、Edit をサポートし、デフォルトは Off です。

1. セキュリティフィールド：
   • 対象フィールド：プライマリメール、プライマリ電話、ソーシャルアイデンティティ、パスワード、MFA。
   • エンドユーザーがこれらのフィールドを編集する前に、パスワード・メール・SMS で本人確認を行い、10分間有効な検証レコード ID を取得する必要があります。詳細は 検証レコード ID の取得 を参照してください。
   • MFA 用に WebAuthn パスキーを利用する場合は、フロントエンドアプリのドメインを WebAuthn 関連オリジン に追加し、アカウントセンターとサインイン体験でパスキーを共有できるようにします。詳細は 新しい WebAuthn パスキーの連携 を参照してください。
2. プロファイルフィールド：
   • 対象フィールド：ユーザー名、名前、アバター、プロファイル（その他標準プロファイル属性）、カスタムデータ。
   • これらは追加の本人確認なしで編集可能です。
3. シークレットボールト：OIDC や OAuth のソーシャル・エンタープライズコネクター用に、Logto の シークレットボールト が認証後のサードパーティアクセストークン・リフレッシュトークンを安全に保存します。これにより、アプリはユーザーに再度サインインを求めることなく Google カレンダーイベントの同期など外部 API を呼び出せます。Account API を有効化すると自動的にトークン取得が可能になります。

Account API へのアクセス方法

注記:

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

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

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

const config: LogtoConfig = {
  // ...他のオプション
  // ユースケースに合ったスコープを追加
  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, // ユーザープロファイル管理用
  ],
};

アクセストークンの取得

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

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

アクセストークンを使った Account API へのアクセス

Account API へリクエストする際は、HTTP ヘッダーの Authorization フィールドに Bearer 形式（Bearer YOUR_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": "..."
}

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

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

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

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

認証について詳しくは 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, // サーバーから返されたデータ
});
// レスポンスを後で利用できるよう保存

ステップ 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