パーソナルアクセストークン (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 リソース に利用できます
- トークン検証:同じ検証ロジックが適用されます — 初期のグラントタイプのみが異なります
組織を扱う場合、PAT でもリフレッシュ トークン (Refresh token) でもアクセスパターンや権限は同じです。
リクエスト
アプリケーションは、HTTP POST メソッドを使い、特別なグラントタイプでテナントの トークンエンドポイント へ トークンエクスチェンジリクエスト を送信します。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 アプリケーションの場合:
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%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange
&resource=http://my-api.com
&scope=read
&subject_token=pat_W51arOqe7nynW75nWhvYogyc
&subject_token_type=urn%3Alogto%3Atoken-type%3Apersonal_access_token
アプリシークレットを持たないシングルページまたはネイティブアプリケーションの場合:
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%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange
&resource=http://my-api.com
&scope=read
&subject_token=pat_W51arOqe7nynW75nWhvYogyc
&subject_token_type=urn%3Alogto%3Atoken-type%3Apersonal_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 キーの定義と実際の利用シナリオ