Space Access Token

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·allowedReferrers가 있습니다.

{
  "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"]
  },
  "allowedReferrers": [],
  "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: 토큰에 대한 설명입니다(선택).
allowedReferrers: 이 토큰을 어느 origin에서 호출할 수 있는지 제한하는 목록입니다. 목록이 비어 있으면 제한하지 않습니다. 위 예시는 서버에서 호출하는 토큰이라 목록을 비워 두었습니다(표기 규칙과 판정 방식은 origin 표기 규칙과 Referer 판정 참조).

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

시스템 속성 (sys)

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

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

본문 속성:

속성	타입	설명
`name`	string (1~64)	토큰 이름. 생성 시 지정합니다.
`description`	string (≤128)	토큰 설명. 선택입니다.
`allowedReferrers`	string array (0~50)	이 토큰의 호출을 허용할 origin 목록. 빈 목록은 제한하지 않는다는 뜻입니다. 전체 수정은 통째 교체이므로, 이 항목을 빼고 보내면 목록이 비워져 제한이 풀립니다. 제한을 그대로 두려면 현재 목록을 다시 담아 보냅니다. 발급 후에도 바꿀 수 있습니다.

생성 요청 본문 전용 입력:

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

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

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

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

상태와 제약

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

대상	제약
`name`	1~64자, 필수(생성 시).
`description`	128자 이하, 선택.
`role`	SpaceRole의 `Refer`, 필수(생성 시).
`allowedReferrers`	항목 0~50개. 각 항목은 아래 origin 표기 규칙을 지켜야 합니다.

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

바인딩할 role은 그 Space에 실제로 존재해야 합니다. 없는 역할의 sys.id를 넣으면 생성이 거부됩니다.
호출자는 자신이 그 Space에서 가진 역할만 바인딩할 수 있습니다. 자신에게 없는 역할을 바인딩해 토큰에 더 높은 권한을 부여하는 것을 막기 위한 제약이며, 이를 어긴 생성 요청은 거부됩니다. 단 그 Space의 관리자(Administrator 역할 보유자)는 이 제약을 받지 않고 어떤 역할이든 바인딩할 수 있습니다.
Space Access Token은 개수 한도가 있는 리소스입니다. 현재 플랜의 발급 개수 한도를 넘으면 생성이 거부됩니다. 플랜별 한도는 요금제를 참조하세요.
발급·관리(생성·조회·수정·삭제)에는 호출자 역할의 settings에 SETTING_SPACE_ACCESS_TOKEN이 있어야 합니다. 읽기 전용 Delivery Access Token을 발급하는 SETTING_DELIVERY_ACCESS_TOKEN과는 별개 액션이라, 전달 토큰 발급 권한만 주고 이 토큰 발급은 막을 수 있습니다(SpaceRole 참조).
이 API는 콘솔 로그인 세션과 Personal Access Token으로만 호출됩니다. Space Access Token 자신으로는 다른 Space Access Token을 만들 수 없고, 이는 바인딩한 역할에 SETTING_SPACE_ACCESS_TOKEN을 넣어도 마찬가지입니다.

origin 표기 규칙

allowedReferrers의 각 항목은 호출을 허용할 origin 하나를 가리키는 문자열입니다. 다음 모양으로 적습니다.

"allowedReferrers": [
  "https://shop.example.com",
  "https://*.shop.example.com",
  "http://localhost:3000"
]

목록에는 항목을 최대 50개까지 담고, 같은 origin을 두 번 넣을 수 없습니다. 항목마다 지켜야 하는 규칙은 다음과 같습니다.

스킴은 https만 씁니다. http는 localhost·127.0.0.1·[::1]에만 허용합니다.
와일드카드는 맨 앞의 *. 라벨 하나로만 씁니다. 경로에는 쓸 수 없습니다.
호스트는 ASCII로 적습니다. 국제화 도메인은 퓨니코드 표기로 넣습니다.
포트는 1부터 65535까지입니다. 생략하면 스킴의 기본 포트(https는 443, http는 80)로 봅니다.
경로를 적으면 요청의 경로와 정확히 같을 때만 통과합니다. 브라우저가 경로를 퍼센트 인코딩해 보내므로 경로에는 ASCII만 씁니다.
사용자 정보(user@)나 쿼리(?), 프래그먼트(#)가 붙은 항목은 거부합니다.

이 검사는 생성·전체 수정·부분 수정 세 경로 모두에서 걸립니다. 규칙에 어긋난 항목이 하나라도 있으면 목록을 저장하지 않고 요청을 거부하며, 어긋난 항목 하나를 오류 사유에 담아 알려 줍니다(오류 참조).

Referer 판정

발급한 뒤 이 토큰으로 API를 호출하면, 요청마다 allowedReferrers를 적용해 통과 여부를 판정합니다.

목록이 비어 있으면 제한하지 않습니다. 어느 origin에서 호출해도 통과합니다.
목록에 항목이 하나라도 있으면 요청의 Referer 헤더 값으로 판정합니다. Origin 헤더는 보지 않습니다.
Referer 헤더가 없거나 값이 비어 있으면 거부합니다. 서버끼리 주고받는 호출처럼 Referer를 보내지 않는 곳에서 쓸 토큰은 목록을 비워 둡니다.
통과하려면 Referer의 스킴·호스트·포트가 목록의 한 항목과 모두 같아야 합니다. 그 항목에 경로가 있으면 경로까지 같아야 합니다.
https://*.shop.example.com은 admin.shop.example.com처럼 .shop.example.com으로 끝나는 호스트를 모두 포함하고, shop.example.com 자신은 포함하지 않습니다. 둘 다 허용하려면 https://shop.example.com을 항목으로 하나 더 넣습니다.
이 판정은 이 토큰으로 보내는 모든 요청에 걸립니다. CMA·CDA 어느 경로를 호출하든 같습니다.
판정에 걸린 요청은 HTTP 403으로 거부됩니다. 돌아오는 코드는 아래 오류에 있습니다.

오류

Space Access Token을 다룰 때 만나는 코드입니다. 모든 리소스에 공통인 코드는 공통 오류를 참조하세요.

코드	조건
`WGL400071`	`allowedReferrers`에 origin 표기 규칙에 어긋난 항목을 넣었습니다. 생성·전체 수정·부분 수정 모두에서 검사합니다.
`WGL404001`	`role`에 그 Space에 없는 SpaceRole의 `sys.id`를 넣었습니다.
`WGL422001`	호출자가 그 Space에서 자신이 갖지 않은 SpaceRole을 토큰에 바인딩하려 했습니다. 그 Space의 관리자(Administrator 역할 보유자)는 이 제약을 받지 않습니다.
`WGL429001`	발급한 Space Access Token 개수가 현재 플랜의 한도에 이른 상태에서 토큰을 새로 발급하려 했습니다.
`WGL403001`	호출자의 역할에 `SETTING_SPACE_ACCESS_TOKEN` 설정 권한이 없습니다. 발급뿐 아니라 조회·수정·삭제에도 필요합니다.
`WEB403001`	`allowedReferrers`를 지정한 토큰으로 목록에 없는 origin에서 호출했거나, 요청에 `Referer`가 없습니다. 이 코드는 토큰을 다룰 때가 아니라 그 토큰으로 요청할 때 돌아옵니다.

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 발급 개수 한도.