APIキーを取得

Kaleidr は1つのプラットフォーム、1つの SDK、1つのアクセスシステムで AI、マップ、デザインを提供し、 capability scope によって制御されます。キーには実行場所に応じて2つの安全な形式があり、 どちらも同じ組織に属し、同じクォータから使用量が差し引かれます。

形式	プレフィックス	使用場所	機能
Publishable（ブラウザ）	kld_pk_live_…	HTML、SDK、<kaleidr-map> 内	origin に制限され、ページソース内でも安全です。SDK が実行時に短時間有効なセッションと交換します。server bearer として使用したり、キーを管理したりすることはできません。
Server（バックエンド）	kld_sk_live_…	サーバーのみ	サーバー間呼び出し用の完全な bearer。任意の IP allowlist、上限、期限を設定できます。ブラウザではブロックされます（403 server_key_in_browser）。

既存のレガシー kld_live_… キーは変更なく引き続き認証できます。

各プランで利用できる内容

これは正式なプラン → scope × product ポリシーです。この表は @kaleidr/shared-types の B2B_TIER_API_CAPABILITIES と常に一致するよう管理されています — これは shared-api がキー発行時に、inference-api がセッション交換時に参照する 同じ定数です。CI drift guard によって、ここに記載された内容と実際に プラットフォームが許可する内容が密かに食い違うことを防ぎます。

プラン	Publishable	Server	許可されるスコープ	許可される製品
Free	はい	— (403 free_plan_publishable_only)	maps	tile
Pro	はい	はい	ai, maps, design, vendor*	chat, editor, viewer, tile
Enterprise	はい	はい	ai, maps, design, vendor*	chat, editor, viewer, tile

* vendor はキーごとに明示的な確認が必要です（確認がない場合は 403 vendor_scope_requires_acknowledgement）。

Viewer にキーは一切不要です — share id 自体が認証情報です。Free を含むすべてのプランで キーなしで Viewer を埋め込めます。Viewer embed にキーを渡すと product_not_allowed で拒否されます。

実際の許可内容は 保存済みキー × 現在のプラン で決まります。 Pro のキーを Free にダウングレードすると、サーバーは Free 相当のセッションを発行します — maps スコープと tile 製品のみです。Free のキーを再び広い権限に戻すには、 既存のキーを編集するのではなく、上位プランで新しいキーを発行する必要があります（ Errors — Key management を参照）。

テストキー

どちらの形式にも test バリアントがあります（kld_pk_test_…, kld_sk_test_…）。

テストキーは sandbox ではありません。同じ API に対して認証し、 同じモデルを呼び出し、live キーと同じ月間利用枠を消費します。 異なる点は2つです：

• test publishable key は origin allowlist なしでも作成できますが、 live key ではできません；
• test key は basemap tiles を配信できません。

テストキーは staging トラフィックを識別可能にし、個別に 失効できるようにするために使用してください — それが本来の価値です。無料のキーとして扱わないでください。

キーを発行する

1. サインインし、アカウントの API Keys を開きます （kaleidr.com/api-keys）— 組織の管理者 のみ利用できます。
2. キーを作成 — 名前を付け、Browser（publishable）または Server を選びます。Pro と Enterprise では、そのプランで利用可能なすべての権限 （ai, maps, design scopes；chat, editor, viewer, tile products）が付与されます。Free では maps / tile に制限された Browser key となり、Server オプションはありません。
3. live Browser key には少なくとも1つの allowed origin を設定する必要があります — origin のない live publishable key は、 ページソース上に恒久的な秘密情報となってしまうため拒否されます。
4. kld_pk_live_… / kld_sk_live_… の値を 一度だけ コピーしてください — 一度しか表示されず、再表示されません。

すべての埋め込みに必要な2つの前提条件

現在、どちらも各製品ページには記載されておらず、それぞれ単独で 最初の統合を停止させる可能性があります。

1. Origin allowlist

セッション交換では、ブラウザの Origin ヘッダーとキーの allowlist を照合します。 一致しない場合は 403 session_origin_mismatch で拒否されます。file:// は Origin を一切送信しません — コピーしたスニペットを最初に試す際によく使われる方法ですが — キーを使用する埋め込みはすべて HTTP(S) で配信してください。

既存キーの allowlist は、プラットフォームキー自体ではなく Cognito の org-admin JWT を使用して更新します：

PATCH /shared-api/api-keys/{key_id}
Authorization: Bearer {cognito_org_admin_jwt}
Content-Type: application/json

{ "allowed_origins": ["https://your.site", "https://staging.your.site"] }

PATCH はキーの snapshot cache を即座に無効化し、origin を削除すると その origin にすでに紐づいているセッションも終了します — 各セッションリクエストは 現在の allowed_origins に対して origin を再確認するため、削除された origin からの 次のリクエストは TTL の終了を待たずに拒否されます。 origin を追加した場合は逆で、新しいセッションは許可されますが、既存セッションには 遡って紐づけられません。

2. 顧客側 CSP

ページの Content Security Policy は、各製品が読み込むリソースを許可する必要があります。 製品ごとの設定については Content Security Policy を参照してください — Tile と Viewer は SDK loader と1つの frame host のみを追加します。 Chat と Editor は MapLibre が親ドキュメント内で動作するため、さらに 'wasm-unsafe-eval' とマップベンダーの host が必要です。

使用方法

ブラウザでは publishable key を渡すと、SDK がそれを短時間有効な セッションと交換します：

<kaleidr-map product="tile"
             publishable-key="kld_pk_live_…"
             style-id="kaleidr-morning"
             style="height:480px"></kaleidr-map>

サーバーからは server key を bearer として送信します：

Authorization: Bearer kld_sk_live_…

キーはあなたの組織として認証されます。使用量は組織の 月間クォータ から差し引かれます。 各スコープで利用できる内容は Auth & scopes を、 各セッション交換を制御するブラウザ origin allowlist については CORS & allowed origins を参照してください。