Account API によるアカウント設定

Logto Account API とは

Logto Account API は、エンドユーザーが Management API を経由せずに直接 API にアクセスできる包括的な API セットです。以下はそのハイライトです：

直接アクセス: Account API は、エンドユーザーが自分のアカウントプロファイルに直接アクセスし管理することを可能にし、Management API の中継を必要としません。
ユーザープロファイルとアイデンティティ管理: ユーザーは、メール、電話、パスワードなどのアイデンティティ情報の更新やソーシャル接続の管理を含む、プロファイルとセキュリティ設定を完全に管理できます。MFA と SSO のサポートは近日中に提供予定です。
グローバルアクセス制御: 管理者はアクセス設定を完全にグローバルに制御でき、各フィールドをカスタマイズできます。
シームレスな認可 (Authorization): 認可 (Authorization) はこれまでになく簡単です！client.getAccessToken() を使用して OP (Logto) の不透明トークンを取得し、Bearer <access_token> として Authorization ヘッダーに添付します。

Logto Account API を使用すると、Logto と完全に統合されたプロファイルページのようなカスタムアカウント管理システムを構築できます。

以下は一般的な使用例です：

ユーザープロファイルの取得
ユーザープロファイルの更新
ユーザーパスワードの更新
メール、電話、ソーシャル接続を含むユーザーアイデンティティの更新
MFA 要素（検証）の管理
ユーザーセッションの管理
ユーザー承認アプリ（グラント）の管理

利用可能な API について詳しく知るには、 Logto Account API Reference と Logto Verification API Reference をご覧ください。

注記:

SSO アカウントの表示とアカウント削除機能は現在、Logto Management API を通じて利用可能です。実装の詳細については、 Management API によるアカウント設定を参照してください。

Account API を有効にする方法

Console > Sign-in & account > Account center

に移動します。

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

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

セキュリティフィールド：
- フィールドには、プライマリメール、プライマリ電話、ソーシャルアイデンティティ、パスワード、MFA が含まれます。
- エンドユーザーがこれらのフィールドを編集する前に、パスワード、メール、または SMS を介して自分のアイデンティティを確認し、10 分間の検証レコード ID を取得する必要があります。 Get a verification record id を参照してください。
- MFA に WebAuthn パスキーを使用するには、フロントエンドアプリのドメインを WebAuthn Related Origins に追加し、アカウントセンターとサインイン体験でパスキーを共有できるようにします。 Link a new WebAuthn passkey を参照してください。
プロファイルフィールド：
- フィールドには、ユーザー名、名前、アバター、プロファイル（他の標準プロファイル属性）、およびカスタムデータが含まれます。
- エンドユーザーは追加の検証なしでこれらを編集できます。
シークレットボールト：
- OIDC または OAuth ソーシャルおよびエンタープライズコネクターの場合、Logto シークレットボールトは、認証後にサードパーティのアクセスおよびリフレッシュトークンを安全に保存します。これにより、アプリはユーザーに再度サインインを促すことなく、Google カレンダーイベントの同期などの外部 API を呼び出すことができます。Account API が有効になると、トークンの取得が自動的に利用可能になります。
セッション管理：
- 有効にすると、ユーザーはアクティブなセッションを表示および管理でき、デバイス情報や最後のサインイン時間を含みます。ユーザーは特定のデバイスからログアウトするためにセッションを取り消すこともできます。
- この同じ Sessions フィールドの権限は、ユーザー承認アプリ（グラント）API（表示およびグラントの取り消し）も制御します。
- エンドユーザーがセッション管理にアクセスする前に、パスワード、メール、または SMS を介して自分のアイデンティティを確認し、10 分間の検証レコード ID を取得する必要があります。 Get a verification record 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 = {
  // ...other options
  // 使用例に適したスコープを追加します。
  scopes: [
    UserScope.Email, // `{POST,DELETE} /api/my-account/primary-email` API 用
    UserScope.Phone, // `{POST,DELETE} /api/my-account/primary-phone` API 用
    UserScope.CustomData, // カスタムデータを管理するため
    UserScope.Address, // 住所を管理するため
    UserScope.Identities, // アイデンティティおよび MFA 関連の API 用
    UserScope.Profile, // ユーザープロファイルを管理するため
    UserScope.Sessions, // ユーザーセッションとアプリグラントを管理するため
  ],
};

アクセストークンを取得する

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

公式 SDK を使用していない場合は、アクセストークンの付与リクエストに対して 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": "..."
}

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

基本的なアカウント情報を更新する

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

ユーザー名、名前、アバター、およびカスタムデータ を更新するには、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 分間の有効期限 (TTL) を持つ 検証レコード ID を取得する必要があります。これは、機密情報を更新する前にユーザーのアイデンティティを確認するために使用できます。つまり、ユーザーがパスワード、メール検証コード、または SMS 検証コードを介して自分のアイデンティティを正常に確認すると、識別子、資格情報、ソーシャルアカウントのリンク、および MFA を含む認証関連データを更新するために 10 分間の時間が与えられます。

検証レコード 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 を通じて設定されたパスワードは、Console > Security > Password policy で設定したパスワードポリシーに準拠している必要があります。Logto は、ポリシーに違反した場合、詳細な検証結果とエラーメッセージを返します。

新しいメールを更新またはリンクする

注記:

この方法を使用するには、メールコネクターを設定する必要があり、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 として設定します。

2 つの異なる検証レコード ID:

このリクエストには、2 つの異なる検証レコード ID が必要です：

logto-verification-id (header): 機密変更を行う前にユーザーのアイデンティティを証明します。これを取得するには、ユーザーのパスワードを確認するか、ユーザーの既存のメールまたは電話に検証コードを送信する必要があります。
newIdentifierVerificationRecordId (body): 新しいメールアドレスの所有権を証明します。これは、上記の 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 を通じてリンクされたメールは、Console > Security > Blocklist で設定したブロックリスト検証に合格する必要があります。Logto は、ポリシーに違反した場合、リクエストを拒否し、詳細なエラーを返します。

ユーザーのメールを削除する

ユーザーのメールを削除するには、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: ユーザーがアプリケーションを認可した後のリダイレクト URI。この URL にウェブページをホストし、コールバックをキャプチャする必要があります。
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 からクエリパラメータを解析して取得し、connectorData フィールドの値として JSON 形式でラップする必要があります。

最後に、POST /api/my-account/identities エンドポイントを使用してソーシャル接続をリンクできます。

2 つの異なる検証レコード ID:

このリクエストには、2 つの異なる検証レコード ID が必要です：

logto-verification-id (header): 機密変更を行う前にユーザーのアイデンティティを証明します。これを取得するには、ユーザーのパスワードを確認するか、ユーザーの既存のメールまたは電話に検証コードを送信する必要があります。
newIdentifierVerificationRecordId (body): リンクされるソーシャルアイデンティティを識別します。これは、上記の 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 を呼び出すため、クロスオリジンのパスキー操作を許可するために Related Origins を設定する必要があります。

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 は、各ユーザーアカウントに複数のパスキーを登録することを許可しています。

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 でサーバーから返されたデータ
});
// 後で使用するためにレスポンスを保存します

ステップ 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。詳細については、 Get a verification record 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:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=YourApp

ステップ 3: TOTP 要素をバインドする

ユーザーがシークレットを認証アプリに追加した後、それを確認し、アカウントにバインドする必要があります。POST /api/my-account/mfa-verifications エンドポイントを使用して 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。詳細については、 Get a verification record ID セクションを参照してください。
type: Totp である必要があります。
secret: ステップ 1 で生成された TOTP シークレット。

注記:

ユーザーは一度に 1 つの TOTP 要素しか持つことができません。ユーザーがすでに 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: ユーザーにバックアップコードを表示する

バックアップコードをユーザーのアカウントにバインドする前に、ユーザーに表示し、次のことを指示します：

これらのコードをすぐにダウンロードまたは書き留める
安全な場所に保管する
各コードは一度しか使用できないことを理解する
これらのコードがプライマリ 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。詳細については、 Get a verification record ID セクションを参照してください。
type: BackupCode である必要があります。
codes: 前のステップで生成されたバックアップコードの配列。

注記:

ユーザーは一度に 1 セットのバックアップコードしか持つことができません。すべてのコードが使用された場合、ユーザーは新しいコードを生成してバインドする必要があります。
バックアップコードは唯一の MFA 要素にはなり得ません。ユーザーは少なくとも 1 つの他の MFA 要素（WebAuthn や TOTP など）を有効にしている必要があります。
各バックアップコードは一度しか使用できません。

既存のバックアップコードを表示する

既存のバックアップコードとその使用状況を表示するには、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。

ユーザーセッションを管理する

アクティブなセッションを一覧表示する

ユーザーのアクティブなセッションを一覧表示するには、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: セッションに関連付けられたファーストパーティアプリのグラントのみを取り消します。（ほとんどの使用例に推奨されます。これにより、サードパーティアプリのグラントを保持しながら、自分のアプリのアクセスを取り消し、より良いユーザーエクスペリエンスを提供します。）
- 指定なし: デフォルトの動作は、通常、セッションのリフレッシュトークン以外のグラントを取り消すことを意味します。

ユーザー承認アプリ（グラント）を管理する

ユーザーがアカウント設定ページから承認されたアプリを確認および取り消す必要がある場合に、ユーザー承認アプリ（グラント）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'

グラントが取り消されると、そのグラントに対して以前に発行された不透明トークンとリフレッシュトークンは無効になります。

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 をリンクする

バックアップコードを管理する

ユーザーセッションを管理する

ユーザー承認アプリ（グラント）を管理する