Space Access Token

Space Access Tokenは、1つのSpaceの中でコンテンツを読み書きできるトークンです。CMAでコンテンツを生成・修正・削除でき、CDAの読み取りとUploadもこのトークンで呼び出します。発行時に1つのSpaceRoleにバインドし、そのロールがトークンに何をどこまで許すか(どのContent Typeをどの操作で扱えるか)を定めます。

読み取り専用のDelivery Access Tokenとは異なり、このトークンは書き込みまで行えます。一方、ユーザーアカウント全体に結びつくPersonal Access Tokenとは異なり、1つの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です。トークンはこのSpace1つの中でのみ動作します。
• 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" } })で入ります。

本文の属性:

生成リクエスト本文専用の入力:

セキュリティ: 露出範囲に合わせたロールバインディング

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は発行後も同じ値で取得できる秘密の値です。露出する必要のない場所では、コード・ログ・ストレージ・エラーメッセージに平文で残さず、露出が疑われる場合は削除して無効化し、新しいトークンに差し替えます。

状態と制約

生成・修正時に守る値の制約です。

バインドと権限についてのルール:

• バインドする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を1つ指す文字列です。次の形で書きます。

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

一覧には項目を最大50個まで含められ、同じoriginを二度入れることはできません。項目ごとに守るべきルールは次のとおりです。

• スキームはhttpsだけを使います。httpはlocalhost・127.0.0.1・[::1]にのみ許可されます。
• ワイルドカードは先頭の*.ラベル1つとしてのみ使えます。パスには使えません。
• ホストはASCIIで書きます。国際化ドメインはPunycode表記で入れます。
• ポートは1から65535までです。省略するとスキームの既定ポート(httpsは443、httpは80)として扱います。
• パスを書いた場合は、リクエストのパスと完全に一致するときだけ通過します。ブラウザはパスをパーセントエンコードして送るため、パスにはASCIIだけを使います。
• ユーザー情報(user@)やクエリ(?)、フラグメント(#)が付いた項目は拒否されます。

この検査は、生成・全体更新・部分更新の3つの経路すべてで行われます。ルールに反する項目が1つでもあると、一覧を保存せずリクエストを拒否し、反した項目を1つエラーの理由に含めて知らせます(エラーを参照)。

Referer の判定

発行後にこのトークンでAPIを呼び出すと、リクエストごとにallowedReferrersを適用して通過するかどうかを判定します。

• 一覧が空なら制限しません。どのoriginから呼び出しても通過します。
• 一覧に項目が1つでもあれば、リクエストのRefererヘッダーの値で判定します。Originヘッダーは見ません。
• Refererヘッダーがない、または値が空のリクエストは拒否されます。サーバー同士でやり取りする呼び出しのようにRefererを送らない場所で使うトークンは、一覧を空にしておきます。
• 通過するには、Refererのスキーム・ホスト・ポートが一覧のいずれか1つの項目とすべて一致していなければなりません。その項目にパスがある場合は、パスまで一致していなければなりません。
• https://*.shop.example.comは、admin.shop.example.comのように.shop.example.comで終わるホストをすべて含み、shop.example.com自身は含みません。両方を許可するには、https://shop.example.comを項目としてもう1つ入れます。
• この判定は、このトークンで送るすべてのリクエストに適用されます。CMA・CDAのどのパスを呼び出しても同じです。
• 判定で弾かれたリクエストはHTTP 403で拒否されます。返るコードは下記のエラーにあります。

エラー

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発行数の上限。