メインコンテンツまでスキップ

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> として付与するだけです。
注記:

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

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

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

const config: LogtoConfig = {
  // ...他のオプション
  // 利用ケースに合わせて適切なスコープ (Scope) を追加してください。
  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, // ユーザープロファイル管理用
  ],
};

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

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

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

利用可能な 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：ソーシャル接続
  • mfa：MFA 要素

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

Account API へのアクセス方法​

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

アプリケーションに SDK をセットアップした後、client.getAccessToken() メソッドでアクセストークン (Access token) を取得できます。このトークンは 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 を取得するには、ユーザーのパスワードを検証するか、メールまたは電話に検証コードを送信します。

検証について詳しくは Account API によるセキュリティ検証 を参照してください。

ユーザーのパスワードによる検証​

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：ユーザーがアプリケーションを認可した後のリダイレクト先。ここでコールバックを受け取る 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>'
注記:

まず MFA および WebAuthn を有効化 してください。

注記:

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

ステップ 0：フロントエンドアプリのオリジンを関連オリジンに追加

ブラウザのパスキーは特定のホスト名（RP ID）に紐づき、RP ID のオリジンのみがパスキーの登録・検証に利用できます。しかし、Account API へリクエストを送るフロントエンドアプリは Logto のサインインページとは異なるため、関連オリジンリストにフロントエンドアプリのオリジンを追加する必要があります。これにより他の RP ID でもパスキーの登録・検証が可能になります。

デフォルトでは RP ID はテナントドメインです。例：https://example.logto.app なら RP ID は example.logto.app。カスタムドメインの場合はそのドメインが RP ID になります。

例：フロントエンドアプリのオリジンが https://account.example.com の場合、関連オリジンに追加します：

curl -X PATCH https://[tenant-id].logto.app/api/webauthn-connectors \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"webauthnRelatedOrigins":["https://account.example.com"]}'

関連オリジンについて詳しくは Related Origin Requests ドキュメントを参照してください。

ステップ 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": "..."
}

ステップ 2：ローカルブラウザでパスキーを登録

@simplewebauthn/browser を例に、startRegistration 関数でローカルブラウザにパスキーを登録します。

import { startRegistration } from '@simplewebauthn/browser';

// ...
const response = await startRegistration({
  optionsJSON: registrationOptions, // ステップ 1 でサーバーから返されたデータ
});
// 後で使うために response を保存

ステップ 3：パスキーの検証

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

ステップ 4：パスキーをリンク

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：パスキーのユーザーエージェント

パスキー名の更新：

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":"..."}'

パスキーの削除：

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