Personal Access Token

PersonalAccessToken은 Weegloo 플랫폼 계정(Weegloo User)이 서버·CI·스크립트에서 자기 권한으로 CMA·Upload·CDA를 호출할 때 쓰는 장기 토큰입니다. 브라우저 로그인 흐름이 매번 발급하는 단기 토큰과 달리, 한 번 발급하면 삭제할 때까지 계속 유효합니다.

PersonalAccessToken은 Space가 아니라 사용자 계정에 묶입니다. 그래서 엔드포인트가 /spaces/{spaceId} 아래가 아니라 최상위 /personal-access-tokens 경로에 있고, 경로 변수에 spaceId가 없습니다. 이 토큰을 쓰는 호출자는 그 사용자가 가입한 모든 Space에서, 각 Space의 SpaceRole이 정한 권한만큼 동작합니다.

리소스 구조

다음은 PersonalAccessToken을 생성했을 때의 응답입니다. sys(시스템 속성)에 토큰 값과 범위가 담기고, 본문에 name이 있습니다.

{
  "sys": {
    "id": "5KmQ2pVnRb8sTfWcXd3LhJ9gAe",
    "type": "PersonalAccessToken",
    "createdBy": { "sys": { "id": "2bN7kRpQ9mWx4Lt6Vy0Cf3Hs8", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-06-18T11:41:47.409Z",
    "updatedBy": { "sys": { "id": "2bN7kRpQ9mWx4Lt6Vy0Cf3Hs8", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-06-18T11:41:47.409Z",
    "accessToken": "PSNAT5SCq8Lm2vK9pXfR1Zt0Nc4Wd6Hg5Ua2Ee9Ck3PoYx8Bj6Hg5Ua2Ee9Ck3Po…",
    "scopes": ["PERSONAL"]
  },
  "name": "상품 동기화 서버"
}

주요 키:

• sys.id: PersonalAccessToken의 고유 식별자입니다. 단일 조회·삭제 경로의 {personalAccessTokenId}에 들어갑니다.
• sys.accessToken: API 호출에 쓰는 비밀 토큰 값입니다. 생성 응답뿐 아니라 이후 조회 응답에도 같은 값이 그대로 나오므로 노출에 주의해야 합니다(아래 보안 절 참조).
• sys.scopes: 토큰의 권한 범위입니다. PersonalAccessToken은 발급 시 항상 ["PERSONAL"]입니다.
• name: 생성할 때 지정한 토큰 이름입니다(예: 상품 동기화 서버).

위 예시의 accessToken은 비밀 값이라 예시 문자열로 대체했습니다. 실제로는 PSNAT로 시작하는 길고 불투명한 문자열이며, 발급한 뒤 다시 조회해도 같은 값이 나옵니다.

시스템 속성 (sys)

모든 PersonalAccessToken은 공통 시스템 속성과 토큰 고유 속성을 sys 객체에 담습니다. createdBy, updatedBy는 Refer 모양({ "sys": { "id", "type": "Refer", "targetType" } })으로 들어갑니다. 이 리소스에는 space가 없습니다. Space에 묶이지 않고 사용자 계정에 묶이는 사용자 레벨 토큰이기 때문입니다.

본문 속성:

보안: 노출하지 않기

PersonalAccessToken은 그 사용자의 신원을 그대로 지닙니다. 이 토큰으로 호출하면 사용자가 가진 모든 Space 멤버십의 SpaceRole 권한으로 CMA·Upload·CDA를 호출할 수 있습니다. 권한 범위가 넓고 수명이 길어서, 한 번 새어 나가면 그 사용자의 전체 권한이 노출됩니다.

• 어디에도 노출되지 않게 비밀로 다룹니다. 한 번 새어 나가면 그 사용자의 전체 권한이 외부로 넘어갑니다. PersonalAccessToken은 서버·CI 등 신뢰된 환경 전용이며, 코드·로그·저장소·오류 메시지 어디에도 평문으로 남기지 않습니다.
• 브라우저·클라이언트 코드에 넣지 않습니다. 브라우저로 내려보낸 값은 사용자가 그대로 들여다볼 수 있어 사실상 공개됩니다. 브라우저에서 동작하는 관리 화면은 콘텐츠 스튜디오 로그인 흐름으로 받는 단기 토큰(화면 세션에 한정)을 씁니다.
• 방문자에게 공개하는 읽기 전용 전달에는 최소 권한(least-privilege) SpaceRole에 묶은 DeliveryAccessToken을 씁니다. 공개 클라이언트에 PersonalAccessToken을 쓰지 않습니다.
• accessToken은 생성 시점뿐 아니라 조회 응답에도 같은 값이 그대로 나옵니다. 조회 결과를 로그·화면·외부 저장소에 그대로 남기지 않도록 주의합니다.
• 수정 API가 없습니다(PUT·PATCH 없음). 토큰을 교체하려면 기존 토큰을 삭제하고 새로 발급합니다. 노출이 의심되면 즉시 삭제해 무효화하고 새 토큰으로 바꿉니다.

(출처: weegloo-user-login·weegloo-delivery-access-token 스킬, .claude/rules/weegloo-api-endpoints.md.)

API

아래 모든 엔드포인트의 기준 URL은 https://cma.weegloo.com/v1이며, Authorization 헤더에 CMA를 인증하는 Bearer 토큰이 필요합니다. PersonalAccessToken은 사용자 레벨 리소스라 경로에 spaceId가 없습니다. 또한 수정 API가 없어 목록·생성·단일 조회·삭제 네 가지만 있습니다.

관련 문서

• Delivery Access Token: 방문자에게 공개하는 읽기 전용 전달 토큰(브라우저용).
• SpaceRole: 이 사용자가 각 Space에서 갖는 권한의 범위.