アカウント設定 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) を取得し、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 リファレンスおよび Logto Verification API リファレンスをご覧ください。

注記:

SSO アカウントの閲覧やアカウント削除機能は現在 Logto Management API で提供されています。実装の詳細はアカウント設定 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: ソーシャル連携
mfa: MFA 要素

API の詳細は Logto Management API リファレンスをご覧ください。

Account API へのアクセス方法

アクセストークン (Access token) の取得

アプリケーションに SDK をセットアップした後、client.getAccessToken() メソッドでアクセストークン (Access token) を取得できます。このトークンは Account API へのアクセスに使える不透明トークン (Opaque token) です。

公式 SDK を使用しない場合は、アクセストークン発行リクエスト /oidc/token の resource を空に設定してください。

アクセストークン (Access token) で Account API へアクセス

Account API へリクエストする際は、HTTP ヘッダーの Authorization フィールドに Bearer 形式（Bearer YOUR_TOKEN）でアクセストークン (Access 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 を使ってユーザーの識別子を更新できます。

認証 (Verification) について詳しくは Security verification by 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":"..."}'

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

注記:

この方法を利用するにはメールコネクターを設定し、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 に設定してください。

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>' \
  -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 エンドポイントでユーザーの電話番号を削除できます。

新しいソーシャル連携を追加するには、まず 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 エンドポイントでソーシャル連携を追加します。

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

新しい 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"]}'

関連オリジンについて詳しくは 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 エラーになります。

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

注記:

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

Logto Account API とは​

Account API を有効化する方法​

Account API へのアクセス方法​

アクセス トークン (Access token) の取得​

アクセス トークン (Access token) で Account API へアクセス​

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

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

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

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

検証レコード ID の取得​

ユーザーのパスワードを検証​

メールまたは電話に認証コードを送信して検証​

検証レコード ID を付与してリクエスト送信​

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

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

ユーザーのメールを削除​

電話番号の管理​

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

ソーシャル連携の削除​

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

既存 WebAuthn パスキーの管理​

新しい TOTP の連携​

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

Logto Account API とは

Account API を有効化する方法

Account API へのアクセス方法

アクセストークン (Access token) の取得

アクセストークン (Access token) で Account API へアクセス

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

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

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

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

検証レコード ID の取得

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

メールまたは電話に認証コードを送信して検証

検証レコード ID を付与してリクエスト送信

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

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

ユーザーのメールを削除

電話番号の管理

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

ソーシャル連携の削除

新しい WebAuthn パスキーの連携

既存 WebAuthn パスキーの管理

新しい TOTP の連携

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