Space Access Token

최종 수정: 2026년 7월 23일

Space Access Token은 한 Space 안에서 콘텐츠를 읽고 쓸 수 있는 토큰입니다. CMA로 콘텐츠를 생성·수정·삭제할 수 있고, CDA 읽기와 Upload도 이 토큰으로 호출합니다. 발급할 때 SpaceRole 하나에 바인딩하며, 그 역할이 토큰이 무엇을 어디까지 할 수 있는지(어떤 Content Type을 어떤 동작으로 다룰 수 있는지)를 정합니다.

읽기 전용인 Delivery Access Token과 달리 이 토큰은 쓰기까지 됩니다. 대신 사용자 계정 전체에 묶이는 Personal Access Token과 달리 한 Space로만 한정되며, Space 설정·조직·계정 평면이나 다른 Space에는 접근하지 못합니다. CMA에서 Space Access Token은 Space 하위 리소스이며, 경로는 /spaces/{spaceId}/space-access-tokens를 기준으로 합니다. 이 토큰을 서버에 둘지, 공개된 클라이언트(예: 익명 글쓰기)에 둘지는 서비스에 맞춰 정합니다. 쓰기 권한이 있는 강력한 토큰이므로, 바인딩하는 역할을 그 토큰을 두는 곳의 노출 범위에 맞게 좁혀서 보안을 확보합니다(아래 보안: 노출 범위에 맞춘 역할 바인딩 참조).

리소스 구조

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

{
  "sys": {
    "id": "7WpR4mKq2bTnXfLc8Vd3HsJ9gEyAo",
    "type": "SpaceAccessToken",
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
    "user": { "sys": { "id": "3trmXRLdJIqc9GPBbyFYQQwYT32LnU", "type": "Refer", "targetType": "User" } },
    "createdBy": { "sys": { "id": "9dLmQ2pVnRb8sTfWcXd3LhJ7gK", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-06-19T02:15:38.472Z",
    "updatedBy": { "sys": { "id": "9dLmQ2pVnRb8sTfWcXd3LhJ7gK", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-06-19T02:15:38.472Z",
    "accessToken": "SPCATq8Lm2vK9pXfR1Zt0Nc4Wd6Hg5Ua2Ee9Ck3PoYx8Bj6Hg5Ua2Ee9Ck3Po…",
    "scopes": ["SPACE_ACCESS_TOKEN"]
  },
  "description": "옷가게 쇼핑몰 상품 등록·수정용 서버 토큰",
  "name": "상품 백엔드 서버"
}

주요 키:

  • sys.id: Space Access Token의 고유 식별자입니다. 단일 조회·수정·삭제 경로의 {spaceAccessTokenId}에 들어갑니다.
  • sys.space: 이 토큰이 속한 Space입니다. 토큰은 이 Space 하나에서만 동작합니다.
  • sys.accessToken: API 호출에 쓰는 비밀 토큰 값입니다. SPCAT로 시작하며, 발급 후 조회에서도 같은 값이 그대로 나오므로 노출에 주의해야 합니다(아래 보안 절 참조).
  • sys.scopes: 토큰의 권한 범위입니다. Space Access Token은 발급 시 항상 ["SPACE_ACCESS_TOKEN"]입니다.
  • sys.user: 이 토큰의 권한 주체인 전용 사용자입니다. 발급할 때 자동으로 만들어지며, 바인딩한 SpaceRole의 권한이 이 사용자에게 부여됩니다. 즉 토큰의 실효 권한은 이 사용자에게서 나옵니다. 이 토큰을 실제로 발급한 사람(sys.createdBy)과는 다른 사용자입니다.
  • name: 생성할 때 지정한 토큰 이름입니다(예: 상품 백엔드 서버).
  • description: 토큰에 대한 설명입니다(선택).

role(바인딩할 SpaceRole)은 생성 요청 본문으로만 보내는 입력값이며, 응답 리소스에는 포함되지 않습니다. 바인딩한 역할은 이 토큰 전용 사용자(응답의 sys.user)에게 부여되는 방식이라, 조회 응답에 role 필드로 되돌아오지 않습니다. 위 예시의 accessToken은 비밀 값이라 예시 문자열로 대체했습니다. 실제로는 SPCAT로 시작하는 길고 불투명한 문자열이며, 발급한 뒤 다시 조회해도 같은 값이 나옵니다.

시스템 속성 (sys)

모든 Space Access Token은 공통 시스템 속성과 토큰 고유 속성을 sys 객체에 담습니다. space, user, createdBy, updatedBy는 Refer 모양({ "sys": { "id", "type": "Refer", "targetType" } })으로 들어갑니다.

속성타입설명
idstring리소스 고유 식별자.
typestring리소스 종류. Space Access Token은 항상 "SpaceAccessToken".
spaceRefer<Space>이 토큰이 속한 Space.
userRefer<User>이 토큰의 권한 주체인 전용 사용자. 발급 시 자동 생성되며, 바인딩한 SpaceRole의 권한이 이 사용자에게 부여됩니다(토큰의 실효 권한은 이 사용자에게서 나옵니다). createdBy(실제 발급자)와는 다른 사용자입니다.
createdByRefer<User>이 토큰을 발급한 실제 사용자(권한 주체는 위 user).
createdAtstring (date-time)생성 시각.
updatedByRefer<User>마지막으로 수정한 실제 사용자.
updatedAtstring (date-time)마지막 수정 시각.
accessTokenstringAPI 호출에 쓰는 비밀 토큰 값. SPCAT로 시작합니다. 발급 후 조회에도 그대로 나오므로 외부에 노출되지 않게 다뤄야 합니다.
scopesstring array토큰의 권한 범위. Space Access Token은 항상 ["SPACE_ACCESS_TOKEN"].

본문 속성:

속성타입설명
namestring (1~64)토큰 이름. 생성 시 지정합니다.
descriptionstring (≤128)토큰 설명. 선택입니다.

생성 요청 본문 전용 입력:

속성타입설명
roleRefer<SpaceRole>바인딩할 SpaceRole의 Refer. 필수. 이 역할이 토큰의 읽기·쓰기 범위를 정합니다. 생성할 때만 지정하며, 발급 후에는 바꿀 수 없고 응답에도 나오지 않습니다.

보안: 노출 범위에 맞춘 역할 바인딩

Space Access Token은 쓰기까지 되는 강력한 토큰입니다. 어떤 SpaceRole에 바인딩하느냐가 곧 이 토큰이 할 수 있는 일의 경계이자 보안 경계가 됩니다. 이 토큰을 서버에 둘지, 공개된 클라이언트(예: 익명 글쓰기)에 둘지는 서비스에 맞춰 정하며, 보안은 "어디에 숨기느냐"가 아니라 바인딩한 역할을 노출 범위에 맞게 좁히는 것으로 확보합니다.

  • 생성 요청의 role에는 그 쓰임에 필요한 동작만 허용하는 좁은 SpaceRole의 sys.id를 넣습니다. 상품 등록용 서버 토큰이라면 상품 Content Type의 읽기·쓰기만 허용하는 역할을, 공개된 익명 글쓰기 토큰이라면 게시글 Content Type에 대한 생성(create)만 허용하는 역할처럼, 노출 범위에 맞춰 최소한으로 바인딩합니다.
  • 공개 클라이언트에 노출하는 토큰일수록 역할을 더 좁게 잡습니다. 그 토큰이 유출돼도 감당할 수 있는 범위까지만 허용해야 합니다. Administrator 역할이나 광범위한 쓰기 역할은 공개 토큰에 바인딩하지 않습니다. 또한 SpaceRole 목록의 첫 번째 항목을 무심코 쓰지 말고, 의도한 좁은 역할의 sys.id를 명시적으로 지정합니다.
  • 방문자에게 공개하는 읽기 전용 전달에는 쓰기 권한이 없는 Delivery Access Token이 더 알맞습니다. 쓰기가 필요할 때만 Space Access Token을 쓰고, 그 역할을 노출 범위에 맞게 좁힙니다.
  • accessToken은 발급 후에도 같은 값으로 조회되는 비밀 값입니다. 노출할 필요가 없는 곳에서는 코드·로그·저장소·오류 메시지에 평문으로 남기지 않고, 노출이 의심되면 삭제해 무효화하고 새 토큰으로 바꿉니다.

(출처: weegloo-space-access-token·weegloo-delivery-access-token 스킬, .claude/rules/weegloo-global-rules.md.)

상태와 제약

생성·수정 시 지키는 값 제약입니다.

대상제약
name1~64자, 필수(생성 시).
description128자 이하, 선택.
roleSpaceRole의 Refer, 필수(생성 시).

바인딩과 권한에 대한 규칙:

  • 바인딩할 role은 그 Space에 실제로 존재해야 합니다. 없는 역할의 sys.id를 넣으면 생성이 거부됩니다(WGL404001). 잘못된 spaceId도 같은 코드로 실패합니다.
  • 호출자는 자신이 그 Space에서 가진 역할만 바인딩할 수 있습니다. 자신에게 없는 역할을 바인딩해 토큰에 더 높은 권한을 부여하는 것을 막기 위한 제약이며, 위반하면 WGL422001로 거부됩니다. 단 그 Space의 관리자(Administrator 역할 보유자)는 이 제약을 받지 않고 어떤 역할이든 바인딩할 수 있습니다.
  • Space Access Token은 개수 한도가 있는 리소스입니다. 현재 플랜의 발급 개수 한도를 넘으면 생성이 거부됩니다(WGL429001). 플랜별 한도는 요금제를 참조하세요.
  • 발급·관리(생성·조회·수정·삭제)에는 그 Space의 API 키 설정 권한이 필요합니다. Space Access Token 자신으로는 다른 Space Access Token을 만들 수 없습니다.

API

아래 모든 엔드포인트의 기준 URL은 https://cma.weegloo.com/v1이며, Authorization 헤더에 CMA를 인증하는 Bearer 토큰이 필요합니다. Space Access Token의 수정·부분 수정에는 X-Weegloo-Version 헤더가 필요하지 않습니다.

  • SpaceRole: 이 토큰에 바인딩할 역할(읽기·쓰기 범위)을 정의.
  • Delivery Access Token: 방문자에게 공개하는 읽기 전용 전달 토큰(클라이언트용).
  • Personal Access Token: 계정 전체에 묶이는 서버·CI용 Weegloo User 토큰.
  • 요금제: 플랜별 Space Access Token 발급 개수 한도.