アカウント設定 by 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) を取得し、Bearer <access_token> 形式で Authorization ヘッダーに付与するだけです。

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

よく使われる用途例：

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

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

注記:

以下の設定専用の Account API は近日公開予定です：多要素認証 (MFA)、シングルサインオン (SSO)、カスタムデータ（ユーザー）、アカウント削除。それまでは Logto Management API を利用して実装できます。詳細は Account settings by 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":"..."}'

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

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>'