アカウント設定（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 です。

セキュリティフィールド：
- 対象フィールド：プライマリメール、プライマリ電話、ソーシャルアイデンティティ、パスワード、MFA。
- エンドユーザーがこれらのフィールドを編集する前に、パスワード・メール・SMS いずれかで本人確認を行い、10 分間有効な認証記録 ID を取得する必要があります。詳細は認証記録 ID の取得を参照してください。
- MFA 用に WebAuthn パスキーを利用する場合は、フロントエンドアプリのドメインを WebAuthn 関連オリジン に追加し、アカウントセンターとサインイン体験でパスキーを共有できるようにします。詳細は新しい WebAuthn パスキーの連携を参照してください。
プロファイルフィールド：
- 対象フィールド：ユーザー名、名前、アバター、プロファイル（その他標準プロファイル属性）、カスタムデータ。
- これらは追加認証なしでエンドユーザーが編集可能です。
シークレットボールト：
- OIDC や OAuth のソーシャル・エンタープライズコネクター用に、Logto のシークレットボールトが認証後のサードパーティアクセストークン・リフレッシュトークンを安全に保存します。アプリはユーザーに再サインインを求めずに外部 API（例：Google カレンダー同期）を呼び出せます。Account API 有効化後、自動的にトークン取得が可能になります。
セッション管理：
- 有効化すると、ユーザーは自身のアクティブセッション（デバイス情報や最終サインイン時刻含む）を閲覧・管理できます。特定デバイスのセッションを取り消してログアウトも可能です。
- この Sessions フィールド権限は、ユーザー認可済みアプリ（グラント）API（閲覧・取り消し）にも適用されます。
- エンドユーザーがセッション管理にアクセスする前に、パスワード・メール・SMS いずれかで本人確認を行い、10 分間有効な認証記録 ID を取得する必要があります。詳細は認証記録 ID の取得を参照してください。

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, // ユーザープロファイル管理用
    UserScope.Sessions, // ユーザーセッション・アプリグラント管理用
  ],
};

アクセストークンの取得

アプリケーションで 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":"..."}'

ヒント:

サインアップ時と同様、Account API で設定するパスワードもコンソール＞セキュリティ＞パスワードポリシーで設定したパスワードポリシーに準拠する必要があります。ポリシー違反時は詳細なバリデーション結果とエラーメッセージが返されます。

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

注記:

この方法を利用するには、メールコネクターの設定と 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 でユーザーのメールを更新できます。リクエストボディの newIdentifierVerificationRecordId に verificationId を指定します。

2 種類の認証記録 ID:

このリクエストには 2 つの認証記録 ID が必要です：

logto-verification-id（ヘッダー）：機微な変更前にユーザー本人確認を証明します。ユーザーパスワードの認証または既存メール・電話への認証コード送信で取得します。
newIdentifierVerificationRecordId（ボディ）：新しいメールアドレスの所有権を証明します。上記 POST /api/verifications/verification-code のレスポンスで返される verificationRecordId です。

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_from_existing_identifier>' \
  -H 'content-type: application/json' \
  # "newIdentifierVerificationRecordId" は新メール所有権の証明（上記認証コードフローで取得）
  --data-raw '{"email":"...","newIdentifierVerificationRecordId":"<verification_record_id_from_new_email>"}'

ヒント:

サインアップ時と同様、Account API で連携するメールもコンソール＞セキュリティ＞ブロックリストで設定したブロックリスト検証に合格する必要があります。違反時は詳細なエラーが返されます。

ユーザーメールの削除

ユーザーメールの削除には、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 でソーシャル連携を追加します。

2 種類の認証記録 ID:

このリクエストには 2 つの認証記録 ID が必要です：

logto-verification-id（ヘッダー）：機微な変更前にユーザー本人確認を証明します。ユーザーパスワードの認証または既存メール・電話への認証コード送信で取得します。
newIdentifierVerificationRecordId（ボディ）：連携するソーシャルアイデンティティを識別します。上記 POST /api/verifications/social のレスポンスで返される verificationRecordId です。

curl -X POST https://[tenant-id].logto.app/api/my-account/identities \
  -H 'authorization: Bearer <access_token>' \
  # ユーザー本人確認（パスワードまたは既存メール/電話認証）
  -H 'logto-verification-id: <verification_record_id_from_existing_identifier>' \
  -H 'content-type: application/json' \
  # "newIdentifierVerificationRecordId" は連携するソーシャル連携の識別子（上記ソーシャル認証フローで取得）
  --data-raw '{"newIdentifierVerificationRecordId":"<verification_record_id_from_social>"}'

ソーシャル連携の削除には、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"]}'

注記:

WebAuthn の関連オリジンは最大 5 つのユニークな eTLD+1 ラベルまでサポートされます。eTLD+1（有効なトップレベルドメイン＋1 ラベル）は登録可能なドメイン部分です。例：

https://example.com、https://app.example.com、https://auth.example.com は 1 ラベル（example.com）
https://shopping.com、https://shopping.co.uk、https://shopping.co.jp も 1 ラベル（shopping）
https://example.com と https://another.com は 2 ラベル

5 ドメイン以上を関連オリジンとしてサポートする場合は、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 エラーになります。

既存 TOTP の置き換え

すでに TOTP 要素が設定されている場合、PUT /api/my-account/mfa-verifications/totp エンドポイントで新しいものに置き換えられます。この操作は冪等で、既存 TOTP を削除し新しいものをバインドします。

注記:

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

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

POST /api/my-account/mfa-verifications/totp-secret/generate で新しい TOTP シークレットを生成し、新しい TOTP の連携と同様にユーザーに表示します。

ステップ 2：TOTP 要素の置き換え

curl -X PUT https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"secret":"...","code":"..."}'

verification_record_id：既存要素の認証で取得した有効な認証記録 ID。詳細は認証記録 ID の取得を参照。
secret：ステップ 1 で生成した新しい TOTP シークレット
code：新しいシークレットから生成した TOTP コード（バインド確認用）

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

注記:

まず 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

2 段階認証設定の管理

注記:

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

エンドユーザーは自身のアカウントで 2 段階認証をオン／オフできます。よくある例として、MFA 要素（パスキーなど）を設定しているがサインイン時のみ利用したい場合、2 段階認証を無効化することでサインイン時の MFA プロンプトをスキップし、MFA 要素自体は保持できます。これはユーザーごとの skipMfaOnSignIn 設定で制御します。

現在の MFA 設定の取得

GET /api/my-account/mfa-settings エンドポイントでユーザーの 2 段階認証設定を取得します。

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

レスポンス例：

{
  "skipMfaOnSignIn": false
}

MFA 設定の更新

2 段階認証の有効／無効を切り替えるには、PATCH /api/my-account/mfa-settings エンドポイントを利用します。

curl -X PATCH https://[tenant-id].logto.app/api/my-account/mfa-settings \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"skipMfaOnSignIn":true}'

verification_record_id：有効な認証記録 ID。詳細は認証記録 ID の取得を参照。
skipMfaOnSignIn：true で 2 段階認証を無効化、false で有効化

注記:

この設定は MFA ポリシーが オプション の場合のみ有効です。MFA が必須または 適応型 の場合、skipMfaOnSignIn 設定は無視され、MFA が強制されます。

ユーザーセッションの管理

アクティブセッション一覧の取得

ユーザーのアクティブセッション一覧は GET /api/my-account/sessions エンドポイントで取得できます。

注記:

このエンドポイントには UserScope.Sessions スコープが必要です。
アカウントセンター設定の Sessions フィールドは ReadOnly または Edit に設定してください。

curl https://[tenant-id].logto.app/api/my-account/sessions \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json'

セッション ID 指定でのセッション取り消し

特定セッションの取り消しは DELETE /api/my-account/sessions/{sessionId} エンドポイントで行います。

注記:

このエンドポイントには UserScope.Sessions スコープが必要です。
アカウントセンター設定の Sessions フィールドは Edit に設定してください。

curl -X DELETE https://[tenant-id].logto.app/api/my-account/sessions/{sessionId} \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json'

オプションのクエリパラメータ：

revokeGrantsTarget：セッションと同時に取り消すグラントの対象を指定可能。値：
- all：セッションに紐づくすべてのグラントを取り消し
- firstParty：ファーストパーティアプリのグラントのみ取り消し（自社アプリのみアクセス無効化し、サードパーティアプリは維持。多くのケースで推奨）
- 未指定：デフォルトは offline_access スコープを持たないグラントのみ取り消し（通常はリフレッシュトークンを持たないグラントのみ）

ユーザー認可済みアプリ（グラント）の管理

ユーザーがアカウント設定ページから認可済みアプリを確認・取り消す場合にグラント API を利用します。

注記:

アプリグラント API はセッション API と同じ権限制御モデルを共有します。
UserScope.Sessions スコープが必要です。
アカウントセンター設定の Sessions フィールドは有効化必須：
- ReadOnly または Edit でグラント一覧取得
- Edit でグラント取り消し

アクティブなアプリグラント一覧の取得

現在のユーザーのアクティブなアプリグラント一覧は GET /api/my-account/grants エンドポイントで取得します。

curl https://[tenant-id].logto.app/api/my-account/grants \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json'

オプションのクエリパラメータ：

appType=firstParty：ファーストパーティアプリのグラントのみ返却
appType=thirdParty：サードパーティアプリのグラントのみ返却
appType 省略：すべてのアクティブグラントを返却

curl "https://[tenant-id].logto.app/api/my-account/grants?appType=thirdParty" \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json'

グラント ID 指定でのアプリグラント取り消し

特定アプリグラントの取り消しは DELETE /api/my-account/grants/{grantId} エンドポイントで行います。

curl -X DELETE https://[tenant-id].logto.app/api/my-account/grants/{grantId} \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json'

グラントが取り消されると、これまで発行された不透明トークン（Opaque token）やリフレッシュトークン（Refresh token）は無効化されます。

Logto Account API とは​

Account API の有効化方法​

Account API へのアクセス方法​

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

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

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

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

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

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

認証記録 ID の取得​

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

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

認証記録 ID を付与してリクエスト送信​

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

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

ユーザーメールの削除​

電話番号の管理​

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

ソーシャル連携の削除​

新しい WebAuthn パスキーの連携​

既存 WebAuthn パスキーの管理​

新しい TOTP の連携​

既存 TOTP の置き換え​

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

2 段階認証設定の管理​

ユーザーセッションの管理​

ユーザー認可済みアプリ（グラント）の管理​

Logto Account API とは

Account API の有効化方法

Account API へのアクセス方法

アクセストークンの取得

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

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

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

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

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

認証記録 ID の取得

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

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

認証記録 ID を付与してリクエスト送信

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

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

ユーザーメールの削除

電話番号の管理

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

ソーシャル連携の削除

新しい WebAuthn パスキーの連携

既存 WebAuthn パスキーの管理

新しい TOTP の連携

既存 TOTP の置き換え

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

2 段階認証設定の管理

ユーザーセッションの管理

ユーザー認可済みアプリ（グラント）の管理