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 と完全連携したプロフィールページのようなカスタムアカウント管理システムを構築できます。

よく使われるユースケース例：

• ユーザープロファイルの取得
• ユーザープロファイルの更新
• ユーザーパスワードの更新
• メール、電話、ソーシャル連携などのユーザーアイデンティティの更新

利用可能な API の詳細は Logto Account API Reference および Logto Verification API Reference をご覧ください。

注記:

以下の設定専用の Account API は近日公開予定です：多要素認証 (MFA)、シングルサインオン (SSO)、カスタムデータ（ユーザー）、アカウント削除。それまでは Logto Management API を使ってこれらの機能を実装できます。詳細は Management API によるアカウント設定 をご参照ください。

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: ソーシャル連携

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

Account API へのアクセス方法

アクセストークンの取得

アプリケーションに 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>'

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

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

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 を取得するには、ユーザーのパスワードを検証するか、メールまたは電話に認証コードを送信します。

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

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 を付与してください。

新しいメールの更新または連携

注記:

この方法を利用するには メールコネクター を設定し、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":"..."}'

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

curl -X PATCH 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 で Web ページをホストし、コールバックを受け取る必要があります。
• 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>'