アカウント API によるアカウント設定

Logto アカウント API とは

Logto アカウント API は、エンドユーザーが Management API を経由せずに直接 API にアクセスできる包括的な API セットです。以下がそのハイライトです：

• 直接アクセス：アカウント API は、エンドユーザーが自分のアカウントプロファイルを直接アクセスして管理できるようにし、Management API の中継を必要としません。
• ユーザープロファイルとアイデンティティ管理：ユーザーは、メール、電話、パスワードなどのアイデンティティ情報を更新する能力を含め、プロファイルとセキュリティ設定を完全に管理できます。MFA と SSO のサポートは近日中に提供予定です。
• グローバルアクセス制御：管理者はアクセス設定を完全にグローバルに制御でき、各フィールドをカスタマイズできます。
• シームレスな認可 (Authorization)：認可 (Authorization) はこれまでになく簡単です！client.getAccessToken() を使用して OP (Logto) の不透明トークンを取得し、それを Bearer <access_token> として Authorization ヘッダーに添付します。

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

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

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

利用可能な API について詳しくは、Logto アカウント API リファレンス と Logto 検証 API リファレンス をご覧ください。

アカウント API を有効にする方法

デフォルトでは、アカウント API は無効になっています。有効にするには、Management API を使用してグローバル設定を更新する必要があります。

API エンドポイント /api/account-center を使用してアカウントセンターの設定を取得および更新できます。これを使用してアカウント 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 フィールドはアカウント API を有効または無効にするために使用され、fields フィールドはフィールドをカスタマイズするために使用されます。値は Off、Edit、ReadOnly のいずれかです。デフォルト値は Off です。フィールドのリスト：

• name: 名前フィールド。
• avatar: アバターフィールド。
• profile: プロフィールフィールドとそのサブフィールド。
• username: ユーザーネームフィールド。
• email: メールフィールド。
• phone: 電話フィールド。
• password: パスワードフィールド。取得時に、ユーザーがパスワードを設定している場合は true を返し、そうでない場合は false を返します。
• social: ソーシャル接続。

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

アカウント API にアクセスする方法

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

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

公式 SDK を使用していない場合は、/oidc/token へのアクセストークングラントリクエストで resource を空に設定する必要があります。

アクセストークンを使用してアカウント API にアクセスする

アカウント 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":"..."}'

識別子とその他の機密情報を管理する

セキュリティ上の理由から、識別子やその他の機密情報を含む操作には、アカウント 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 フィールドの値としてラップする必要があります。

最後に、PATCH /api/my-account/identities エンドポイントを使用してソーシャル接続をリンクできます。

curl -X PATCH 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>'