API トークン

API トークンは、ブラウザーでのログインなしにプログラムがあなたに代わって Marketplace へパッケージを提出できる、マシン用の資格情報です。次の 2 つが利用します。

• Z-CMS テーマエディター。管理画面から描いたテーマに署名してそのまま提出するとき（「マーケットプレイスアカウントを接続」）。
• 自分のスクリプトや CI。提出 API を直接呼び出すとき。

トークンにできるのは 1 つだけ ── パッケージを審査に提出することです。パッケージへの署名、他トークンの作成、publisher key の登録・ローテーション、非公開データの読み取りはできません。スコープは submissions:write のみです。署名は引き続きあなたの publisher key で行われ、その鍵はマシンやブラウザーから外に出ません。トークンは署名済みパッケージを Marketplace へ運ぶだけです。

トークンを作成する

Developer Portal → Tokens を開いて作成します。

1. ラベル（Label） ── あなただけに見える名前。後でトークンを見分けるためのものです：my laptop、acme CI。
2. 有効期限（Expiry） ── なし、または 30 / 90 / 365 日。シークレットストアに何か月も置くトークンには終了日を設けるべきで、Portal は期限を過ぎると自動的に拒否します。

作成を押します。完全なトークン（zcms_pat_… の形）はその場で一度だけ表示されます。すぐにコピーしてください。トークンはハッシュとしてのみ保存され、二度と取得できません。失った場合は失効させて作り直してください。

トークンを使う

Z-CMS 管理画面から

テーマエディターの公開パネルで「マーケットプレイスアカウントを接続」を開き、トークンを貼り付けて接続を押します。トークンは暗号化して保存され、以後表示されません。以降、「署名して提出」がこのトークンで署名済みパッケージをアップロードします。

スクリプトや CI から

提出エンドポイントにトークンをベアラー資格情報として送ります。

curl -X POST https://marketplace.z-cms.org/api/v1/developer/submissions \
  -H "Authorization: Bearer zcms_pat_…" \
  -F "file=@corporate-1.2.0.zcms"

提出の一覧・追跡も同じトークンで行えます。

curl https://marketplace.z-cms.org/api/v1/developer/submissions \
  -H "Authorization: Bearer zcms_pat_…"

アップロード上限は 20 MB、各 developer アカウントはスライディング 1 時間あたり最大 10 パッケージまで提出できます。Portal はパッケージ id・バージョン・publisher を署名済みエンベロープから読み取ります。トークンは誰がアップロードしているかを証明するだけです。

管理と失効

トークン一覧には、ラベル、見える prefix（zcms_pat_ と数文字 ── 見分けるには十分、認証には不十分）、作成日時、最終使用日時、有効期限が表示されます。

**失効（Revoke）**はキルスイッチです。失効したトークンでの次のリクエストは即座に失敗します。漏えいが疑われたとき、マシンを廃棄するとき、CI のシークレットをローテーションするときは、すぐに失効させてください。

トークンを安全に保つ

• 場所ごとに 1 トークン ── ラップトップ用に 1 つ、CI ごとに別々に。1 つを失効させても他に影響しません。
• 長期間使うものには有効期限を設定し、無期限のまま放置せず意図的に更新します。
• トークンをコミットしない、公開ページに貼らない。zcms_pat_ の prefix は意図的で、漏えいをシークレットスキャナーが素早く検知できますが、自分で失効させる方が速いです。
• トークンはハッシュとして保存されるため、こちら側のデータベースが漏えいしても使える資格情報にはなりません。あなたの手元のコピーも同じ注意で扱ってください。

関連

• パッケージを公開する ── keygen → pack → 署名 → 提出 の全手順。
• マーケットプレイス概要 ── 審査と配布の仕組み。