パーソナルアクセストークン (Personal access token)

パーソナルアクセストークン (PAT) は、ユーザーが認証情報やインタラクティブなサインインを使用せずにアクセストークン (Access token) を安全に付与する方法を提供します。これは、CI / CD、スクリプト、またはリソースへプログラム的にアクセスする必要があるアプリケーションに便利です。

パーソナルアクセストークンの管理

コンソールを使用する場合

コンソール > ユーザー管理のユーザー詳細ページでパーソナルアクセストークンを管理できます。「認証 (Authentication)」カードで、パーソナルアクセストークンの一覧を確認したり、新規作成したりできます。

Management API を使用する場合

Management API をセットアップした後、API エンドポイントを利用してパーソナルアクセストークンの作成、一覧取得、削除が可能です。

PAT を使ってアクセストークン (Access tokens) を付与する

PAT を作成した後、トークンエクスチェンジエンドポイントを利用してアプリケーションにアクセストークン (Access token) を付与できます。

トークンフローの等価性:

PAT を使用して取得したアクセストークン (Access token) は、標準の refresh_token フローで取得したトークンと同一の動作をします。つまり：

組織コンテキスト：PAT で取得したトークンは、リフレッシュトークン (Refresh token) フローと同じ組織権限やスコープをサポートします
認可フロー：PAT で交換したアクセストークン (Access token) は組織権限や組織レベルの API リソースに利用できます
トークン検証：同じ検証ロジックが適用されます - 初期の grant type だけが異なります

組織を扱う場合、PAT でもリフレッシュトークン (Refresh token) でもアクセスパターンや権限は同じです。

リクエスト

前提条件:

トークンエクスチェンジグラントを使用する前に、アプリケーションで有効化する必要があります：

コンソール > アプリケーションに移動し、対象のアプリケーションを選択します。
アプリケーション設定で「トークンエクスチェンジ」セクションを探します。
「トークンエクスチェンジを許可する」トグルを有効にします。

セキュリティ上の理由から、トークンエクスチェンジはデフォルトで無効になっています。有効化しない場合、「このアプリケーションではトークンエクスチェンジは許可されていません」というエラーが返されます。

アプリケーションは、HTTP POST メソッドを使い、特別な grant type でテナントのトークンエンドポイントへトークンエクスチェンジリクエストを送信します。HTTP リクエストのエンティティボディには application/x-www-form-urlencoded 形式で次のパラメーターを含めます。

client_id: 必須。アプリケーションのクライアント ID。
grant_type: 必須。このパラメーターの値は urn:ietf:params:oauth:grant-type:token-exchange で、トークンエクスチェンジを実行することを示します。
resource: 任意。リソースインジケーター。他のトークンリクエストと同様です。
scope: 任意。リクエストするスコープ。他のトークンリクエストと同様です。
subject_token: 必須。ユーザーの PAT。
subject_token_type: 必須。subject_token パラメーターで提供されるセキュリティトークンのタイプ。このパラメーターの値は urn:logto:token-type:personal_access_token でなければなりません。

レスポンス

トークンエクスチェンジリクエストが成功すると、テナントのトークンエンドポイントはユーザーのアイデンティティを表すアクセストークン (Access token) を返します。レスポンスには、HTTP レスポンスのエンティティボディに application/json 形式で次のパラメーターが含まれます。

access_token: 必須。ユーザーのアクセストークン (Access token)。authorization_code や refresh_token など他のトークンリクエストと同じです。
issued_token_type: 必須。発行されたトークンのタイプ。このパラメーターの値は urn:ietf:params:oauth:token-type:access_token でなければなりません。
token_type: 必須。トークンのタイプ。このパラメーターの値は Bearer でなければなりません。
expires_in: 必須。アクセストークン (Access token) の有効期間（秒単位）。
scope: 任意。アクセストークン (Access token) のスコープ。

トークンエクスチェンジの例

従来の Web アプリケーションやアプリシークレットを持つマシン間通信アプリケーションの場合、Authorization ヘッダーに HTTP Basic 認証で認証情報を含めます：

POST /oidc/token HTTP/1.1
Host: tenant.logto.app
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64(app-id:app-secret)>

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&resource=http://my-api.com
&scope=read
&subject_token=pat_W51arOqe7nynW75nWhvYogyc
&subject_token_type=urn:logto:token-type:personal_access_token

シングルページアプリケーション (SPA) やアプリシークレットを持たないネイティブアプリケーションの場合、リクエストボディに client_id を含めます：

POST /oidc/token HTTP/1.1
Host: tenant.logto.app
Content-Type: application/x-www-form-urlencoded

client_id=your-app-id
&grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&resource=http://my-api.com
&scope=read
&subject_token=pat_W51arOqe7nynW75nWhvYogyc
&subject_token_type=urn:logto:token-type:personal_access_token

成功時のレスポンス例：

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": "eyJhbGci...zg",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read"
}

その後、JWT デコーダーでアクセストークン (Access token) をデコードすると、次のようなアクセストークン (Access token) ペイロードが得られます：

{
  "jti": "VovNyqJ5_tuYac89eTbpF",
  "sub": "rkxl1ops7gs1",
  "iat": 1756908403,
  "exp": 1756912003,
  "scope": "read",
  "client_id": "your-app-id",
  "iss": "https://tenant-id.logto.app/oidc",
  "aud": "http://my-api.com"
}

パーソナルアクセストークンとは？どんなときにパーソナルアクセストークンを使うべき？

パーソナルアクセストークン、マシン間通信認証 (Machine-to-Machine authentication)、API キーの定義と実際の利用シナリオ

パーソナルアクセストークンの管理​

コンソールを使用する場合​

Management API を使用する場合​

PAT を使ってアクセス トークン (Access tokens) を付与する​

リクエスト​

レスポンス​

トークンエクスチェンジの例​

関連リソース​