개인 액세스 토큰 (Personal access token)

개인 액세스 토큰 (PAT, Personal access token)은 사용자가 자격 증명과 상호작용 로그인 없이 액세스 토큰 (Access token)을 안전하게 부여할 수 있는 방법을 제공합니다. 이는 CI/CD, 스크립트, 또는 리소스에 프로그래밍 방식으로 접근해야 하는 애플리케이션에 유용합니다.

개인 액세스 토큰 관리하기

콘솔 사용하기

콘솔 > 사용자 관리의 사용자 상세 페이지에서 개인 액세스 토큰을 관리할 수 있습니다. "인증 (Authentication)" 카드에서 개인 액세스 토큰 목록을 확인하고 새로 생성할 수 있습니다.

Management API 사용하기

Management API를 설정한 후, API 엔드포인트를 사용하여 개인 액세스 토큰을 생성, 조회, 삭제할 수 있습니다.

PAT로 액세스 토큰 부여하기

PAT를 생성한 후, 토큰 교환 엔드포인트를 사용하여 애플리케이션에 액세스 토큰을 부여할 수 있습니다.

토큰 플로우 동등성:

PAT를 사용해 획득한 액세스 토큰은 표준 refresh_token 플로우로 획득한 토큰과 동일하게 동작합니다. 즉:

조직 컨텍스트: PAT로 획득한 토큰은 refresh token 플로우와 동일한 조직 권한 및 스코프를 지원합니다.
인가 (Authorization) 플로우: PAT로 교환한 액세스 토큰을 조직 권한 및 조직 수준 API 리소스에 사용할 수 있습니다.
토큰 검증: 동일한 검증 로직이 적용됩니다. 단, 최초 grant type만 다릅니다.

조직과 함께 작업할 때, PAT 또는 refresh token을 사용하더라도 접근 패턴과 권한은 동일합니다.

요청

애플리케이션은 HTTP POST 메서드를 사용하여 테넌트의 토큰 엔드포인트에 특수 grant type으로 토큰 교환 요청을 보냅니다. 다음 파라미터들은 application/x-www-form-urlencoded 형식으로 HTTP 요청 엔티티 본문에 포함됩니다.

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이어야 합니다.

응답

토큰 교환 요청이 성공하면, 테넌트의 토큰 엔드포인트는 사용자의 아이덴티티를 나타내는 액세스 토큰을 반환합니다. 응답은 application/json 형식으로 HTTP 응답 엔티티 본문에 다음 파라미터를 포함합니다.

access_token: 필수. 사용자의 액세스 토큰으로, authorization_code 또는 refresh_token과 같은 다른 토큰 요청과 동일합니다.
issued_token_type: 필수. 발급된 토큰의 유형. 이 파라미터의 값은 urn:ietf:params:oauth:token-type:access_token이어야 합니다.
token_type: 필수. 토큰의 유형. 이 파라미터의 값은 Bearer이어야 합니다.
expires_in: 필수. 액세스 토큰의 유효 기간(초 단위).
scope: 선택. 액세스 토큰의 스코프.

토큰 교환 예시

앱 시크릿이 있는 전통적인 웹 애플리케이션의 경우:

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 디코더로 액세스 토큰을 디코딩하면 다음과 같은 액세스 토큰 페이로드 예시를 얻을 수 있습니다:

{
  "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로 액세스 토큰 부여하기​

요청​

응답​

토큰 교환 예시​

관련 리소스​

개인 액세스 토큰 관리하기

콘솔 사용하기

Management API 사용하기

PAT로 액세스 토큰 부여하기

요청

응답

토큰 교환 예시

관련 리소스