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 と完全に統合されたプロファイルページのようなカスタムアカウント管理システムを構築できます。

以下に一般的な使用例を示します：

• ユーザープロファイルの取得
• ユーザープロファイルの更新
• ユーザーパスワードの更新
• メール、電話、ソーシャル接続を含むユーザーアイデンティティの更新

利用可能な API について詳しくは、 Logto Account API リファレンス と Logto Verification API リファレンス をご覧ください。

注記:

以下の設定に対する専用の 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 リファレンス を参照してください。

Account API にアクセスする方法

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

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

公式 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 PATCH 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 フィールドをリクエストヘッダーに添付する必要があります。

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

注記:

この方法を使用するには、 メールコネクター を設定し、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 PATCH 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 にウェブページをホストし、コールバックをキャプチャする必要があります。
• state: ユーザーがアプリケーションを認可 (Authorization) した後に返される状態。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>'