Delivery Access Token

DeliveryAccessToken은 CDA(공개 전달)에서 발행된 콘텐츠를 읽을 때 쓰는 읽기용 토큰입니다. 웹사이트나 앱의 브라우저가 발행 콘텐츠를 가져올 때 이 토큰으로 CDA를 호출합니다. 발급할 때 SpaceRole 하나에 바인딩하며, 그 역할이 토큰의 읽기 범위(어떤 Content Type을 읽을 수 있는지)를 정합니다.

CMA에서 DeliveryAccessToken은 Space 하위 리소스이며, 경로는 /spaces/{spaceId}/delivery-access-tokens를 기준으로 합니다. 이 토큰은 브라우저(클라이언트)에 노출된 채로 동작하므로, 바인딩하는 역할은 반드시 필요한 Content Type만 읽는 최소 권한(least-privilege)으로 정해야 합니다(아래 보안: 최소 권한 바인딩 참조). 여기에 더해 allowedReferrers에 호출을 허용할 origin을 담아 두면, 지정한 사이트 밖에서는 이 토큰이 쓰이지 못합니다(origin 표기 규칙과 Referer 판정 참조).

리소스 구조

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

{
  "sys": {
    "id": "3trmXRM3RqbgSnifyg7PUFQuOAqWOc",
    "type": "DeliveryAccessToken",
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
    "user": { "sys": { "id": "3trmXRLdJIqc9GPBbyFYQQw6hf9kGj", "type": "Refer", "targetType": "User" } },
    "createdBy": { "sys": { "id": "3trmXRM3RqbgSnifyg7PUFQsSPi0nt", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-06-18T09:24:23.156Z",
    "updatedBy": { "sys": { "id": "3trmXRM3RqbgSnifyg7PUFQsSPi0nt", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-06-18T09:24:23.156Z",
    "accessToken": "DVRATbQ8mX2vK9pLs7Rf1Zt0Nc4Wd6Hg5Ua2Ee9Ck3PoYx8Bj6Hg5Ua2Ee9Ck3Po…",
    "scopes": ["DELIVERY_ACCESS_TOKEN"]
  },
  "allowedReferrers": ["https://shop.example.com"],
  "description": "옷가게 쇼핑몰 공개 사이트용 읽기 전용 전달 토큰",
  "name": "웹사이트 공개 전달"
}

주요 키:

• sys.id: DeliveryAccessToken의 고유 식별자입니다. 단일 조회·수정·삭제 경로의 {deliveryAccessTokenId}에 들어갑니다.
• sys.accessToken: CDA 호출에 쓰는 비밀 토큰 값입니다. 발급 후 조회에서도 같은 값이 그대로 나오므로 노출에 주의해야 합니다(아래 보안 절 참조).
• sys.scopes: 토큰의 권한 범위입니다. DeliveryAccessToken은 발급 시 항상 ["DELIVERY_ACCESS_TOKEN"]입니다.
• sys.user: 이 토큰의 권한 주체인 전용 사용자입니다. 발급할 때 자동으로 만들어지며, 바인딩한 SpaceRole의 권한이 이 사용자에게 부여됩니다. 즉 토큰의 실효 권한은 이 사용자에게서 나옵니다. 이 토큰을 실제로 발급한 사람(sys.createdBy)과는 다른 사용자입니다.
• name: 생성할 때 지정한 토큰 이름입니다(예: 웹사이트 공개 전달).
• description: 토큰에 대한 설명입니다(선택).
• allowedReferrers: 이 토큰을 어느 origin에서 호출할 수 있는지 제한하는 목록입니다. 목록이 비어 있으면 제한하지 않습니다. 위 예시는 옷가게 공개 사이트(https://shop.example.com)에서 호출할 때만 통과하는 토큰입니다(표기 규칙과 판정 방식은 origin 표기 규칙과 Referer 판정 참조).

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

시스템 속성 (sys)

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

본문 속성:

보안: 최소 권한 바인딩

DeliveryAccessToken은 브라우저와 방문자에게 노출된 채로 CDA를 호출하는 토큰입니다. 그래서 어떤 SpaceRole에 바인딩하느냐가 곧 이 토큰의 보안 경계가 됩니다.

• 생성 요청의 role에는 필요한 Content Type만 읽는 최소 권한 SpaceRole의 sys.id를 넣습니다. 공개 전달에는 읽기 전용 역할을 권장합니다.
• Administrator 역할을 절대 바인딩하지 않습니다. 이 토큰은 클라이언트에 노출되므로, 관리 권한이 달린 역할을 바인딩하면 그 권한이 그대로 외부에 새어 나갑니다. 또한 SpaceRole 목록의 첫 번째 항목을 무심코 쓰지 말고, 의도한 최소 권한 역할의 sys.id를 명시적으로 지정합니다.
• allowedReferrers로 이 토큰을 쓸 수 있는 자리까지 함께 묶습니다. 바인딩한 역할은 이 토큰으로 무엇을 읽을 수 있는지를 정하고, 이 목록은 어디에서 호출할 수 있는지를 정합니다. 브라우저에서 동작하는 토큰은 값 자체를 감출 수 없으므로, 공개 사이트의 origin을 목록에 담아 두면 토큰 값이 밖으로 새어 나가도 그 사이트 밖에서는 CDA 호출이 통과하지 못합니다(Referer 판정 참조).
• accessToken은 발급 후에도 같은 값으로 조회되는 비밀 값입니다. 클라이언트 빌드에 안전하게 주입하되, 외부에 그대로 노출하지 않습니다.

상태와 제약

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

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

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

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 판정

발급한 뒤 이 토큰으로 CDA를 호출하면, 요청마다 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을 항목으로 하나 더 넣습니다.
• 이 판정은 이 토큰으로 보내는 모든 요청에 걸립니다. 어느 CDA 경로를 호출하든 같습니다.
• 판정에 걸린 요청은 HTTP 403으로 거부됩니다. 돌아오는 코드는 아래 오류에 있습니다.

오류

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

API

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

관련 문서

• SpaceRole: 이 토큰에 바인딩할 역할(읽기 범위)을 정의.
• CDA 개요: 이 토큰으로 발행 콘텐츠를 읽는 전달 API.
• Space Access Token: 한 Space 안에서 쓰기까지 되는 토큰(같은 origin 제한을 갖습니다).
• Personal Access Token: 서버·CI용 Weegloo User 토큰.