API キーの取得

APIキーは、Kaleidr に対してお客様の組織を識別するものです。ブラウザーまたはサーバーからキーを使って送信するすべてのリクエストは、組織のプランに基づいて許可され、組織の利用量に計上されます。kaleidr.com/api-keys でキーを作成・管理できます。

Chat、Editor、Tile の利用と、サーバーAPI の呼び出しにはキーが必要です。Viewer で公開済みの地図を埋め込む場合はキーが不要で、地図IDだけで利用できます。

2 種類のキー

キーには2種類あり、使用するコードの実行場所によって選択します。

	公開可能キー	サーバーキー
プレフィックス	`kld_pk_live_…`	`kld_sk_live_…`
実行場所	Webページ内のSDKと `<kaleidr-map>` 要素	お客様のサーバーのみ
ページのソースコードに置けるか	はい	いいえ。パスワードと同様に保護してください。
使用方法	SDKが短時間有効なセッショントークンに交換し、そのセッションでAPIを呼び出します	各リクエストで `Authorization: Bearer` または `X-Api-Key` として直接送信します
制限できる範囲	許可オリジンに登録されたサイト	キーAPIで設定するIP許可リストなどの制限
プラン	Free、Pro、Enterprise	Pro、Enterprise
API Keysページでの名称	Browser / Embed Key	Server Key

訪問者のブラウザー内で動作するものには公開可能キーを使用してください。 このキーは公開されることを前提に設計されています。許可オリジンの一覧と、APIを直接呼び出せない仕組みが保護になります。公開可能キーをAPIエンドポイントに直接渡すと、401 publishable_requires_session で拒否されます。

バックエンドからKaleidrを呼び出す場合はサーバーキーを使用してください。 例として、住所のジオコーディング、独自フロントエンドへの回答ストリーミング、モバイルアプリのバックエンドがあります。ブラウザーが送信する Origin ヘッダーを含むリクエストでは、サーバーキーは403 server_key_in_browser で拒否されます。SDKもリクエスト送信前にサーバーキーによるマウントを拒否します。Webページやモバイルアプリのバイナリにサーバーキーを含めないでください。

両方のキーは同じ組織に属し、利用量の枠も共通です。セッション、組織、計測についてはKaleidrの仕組みを参照してください。

2種類のキーが導入される前に作成されたキーは kld_live_ で始まります。現在も利用でき、サーバーキーと同様に直接送信します。

プランごとに利用できる機能

組織のプランによって作成可能なキーの種類、キーに付与できるスコープ、マウント可能な製品が決まります。

プラン	公開可能	サーバー	許可されるスコープ	許可される製品
Free	可	— (403 `free_plan_publishable_only`)	`ai`、`maps`、`design`	`chat`、`editor`、`viewer`、`tile`
Pro	可	可	`ai`、`maps`、`design`	`chat`、`editor`、`viewer`、`tile`
Enterprise	可	可	`ai`、`maps`、`design`、`vendor`*	`chat`、`editor`、`viewer`、`tile`

* vendor はデフォルトでは含まれず、Enterpriseのキーにのみ付与できます。スコープを参照してください。

各プランでは組織が保持できる有効なキーの数も制限されます。

プラン	有効なキー
Free	2
Pro	10
Enterprise	25

上限を超えると、キーの作成は409 key_limit_reached で拒否されます。新しいキーを作るには既存のキーを失効させてください。キーのローテーションは新規作成に数えられませんが、古いキーは猶予期間が終わるまで上限に含まれます。

この表について重要な点が5つあります。

Freeではブラウザー向けの全製品が使えます。 Chat、Editor、Tile、Viewer をサイトに配置できます。Chatの回答はFreeプランの月間AIクレジットを消費し、使い切ると次の請求期間、追加パック購入、またはプラン変更までリクエストは429になります。
Viewerはプランで利用できるため表にありますが、キーで有効化するわけではありません。 どのプランでも公開済み地図はキーなしで埋め込めます。
Proではサーバーキーと保持可能なキー数が増えます。 バックエンド用サーバーキーを作成でき、有効なキー数は2から10に増えます。スコープと製品はFreeと同じです。
自社の業務データをAIの回答に使用できるのはEnterpriseだけで、アップロード側と参照側の両方に適用されます。 Enterprise組織のオーナーまたは管理者は契約に定める制限内で業務データをアップロードでき、Kaleidr Studioのアシスタントはログイン済みの組織メンバー向けにそのデータを利用します。FreeやProではアップロードできません。APIまたはSDKを通じてデータにアクセスする vendor スコープ付きのキーもEnterprise限定です。FreeやProで vendor を含むキーを作ろうとすると403 tier_capability_not_allowed で拒否されます。詳しくは自社データを参照してください。
Studioの地図へのデータセット追加は全プランで可能です。 ログインしたユーザーはDataパネルで表計算ファイルや地理データをアップロードできます。Freeでは1データセット50,000行、1ファイル32 MiB、組織全体250,000行まで。Proでは100,000行、64 MiB、全体5,000,000行。Enterpriseは1データセットと1ファイルの上限がProと同じ（100,000行、64 MiB）で、組織全体の上限は契約により決まります。これらのデータはStudioや公開地図で表示され、StudioのAIアシスタントの回答にも使われますが、APIキーからは読み取れません。地図のデータセットを参照してください。

価格と利用枠は料金ページをご覧ください。Enterpriseの利用枠は契約により個別に設定します。

スコープ

スコープとはキーに付与される権限です。製品やAPIエンドポイントは必要なスコープを確認します。

スコープ	許可する機能	新しいキー
`ai`	Chatと、サーバーAPIのチャット・場所検索・ジオコーディングのエンドポイント	含まれる
`maps`	Tileのベースマップセッション	含まれる
`design`	EditorとサーバーAPIのデザインエンドポイント	含まれる
`vendor`	組織が公開した業務データをChatの回答に使用できる	含まれない。別途申請が必要。Enterpriseのみ。

API Keysページで作成したキーには必ず ai、maps、design が含まれ、スコープの選択欄はありません。vendor（Enterpriseのみ）の付与や標準スコープの削除が必要な場合はキーAPIを使います。

スコープはキーの作成時に確定します。 後から編集できず、ローテーション時も基本的に引き継ぎます。ただし、現行プランが許可しなくなったスコープは新しいキーから除かれ、FreeでのローテーションはFreeで使えるすべての権限を付与します（プランの変更時を参照）。変更するには新しいキーを作り、古いキーを失効させてください。

プラン変更時の動作

キーが実行できる操作は、キーに付与された権限と現在のプランで認められる機能の共通部分です。リクエストごとに確認されます。

EnterpriseからProまたはFreeへの変更。 既存のキーは動作を続けます。vendor 付きキーの設定にはスコープが残りますが、権限は適用されなくなり、自社業務データを回答に使用しません。エラーは表示されず、一般知識に基づく回答が返ります。変更前に発行されたブラウザーセッションは無効になり、次のリクエストは401を返し、SDKが新プランでセッションを取得します。Proでキーをローテーションすると、vendor を含まない新しいキーになり、他のスコープと許可製品は維持されます。業務データのアップロードは403 vendor_data_not_on_plan で拒否されますが、オーナーと管理者は既存のリリースを一覧表示、非公開、削除できます。

Freeへの変更。 新しいサーバーキーを作れず、保有するサーバーキーや旧形式キーのローテーションも403 free_plan_publishable_only で拒否されます。Freeで公開可能キーをローテーションすると、以前の設定に関係なく ai、maps、design と4製品すべてを許可する新しいキーが発行されます。Studioの地図に追加済みのデータセットは残りますが、新たなアップロードにはFreeのデータセット上限が適用されます。既存のブラウザーセッションは同様に無効化され、SDKが新しく取得します。

上位プランに戻すと、そのプランで利用可能な機能が復活します。設定に vendor が残るキーはEnterpriseで再び自社データにアクセスできます。一方、下位プランでローテーションした代替キーにスコープは復元されないため、新たに作成してください。

キーを作成する

組織のオーナーまたは管理者である必要があります。

kaleidr.com にログインして kaleidr.com/api-keys を開きます。Your API Keys に組織のキーが表示されます。
Create Key を選びます。3つの入力欄を持つ Create a Key ダイアログが開きます。
Key Name。 Production site などのラベルを入力します。訪問者には表示されません。失効時に区別できるよう、使用場所が分かる名前を付けてください。
Key Type。 Browser / Embed Key（公開可能）または Server Key を選びます。FreeにはServer Keyの選択肢がありません。作成後の変更はできません。
Allowed Origins。 公開可能キーでは許可するサイトを https://www.example.com, https://app.example.com のようにカンマ区切りで入力します。空欄ならすべてのサイトを許可します。形式については許可オリジンを参照してください。サーバーキーはサイトに紐付かないため空欄にします。
Create Key を選びます。
その場でキーをコピーします。 「Copy this key now — it won't be shown again.」という警告とともに完全な値が1回だけ表示されます。Copy でコピーして安全に保存し、Done を選びます。Kaleidrは完全なキーを保存しません。紛失したらローテーションして新しい値を取得します。

確認する結果： 新しいキーが表に現れ、Key 欄に先頭の文字、名前、種別（Browser または Server）、Active の状態、当日の日付が表示されます。

"You must be an organization admin to manage API keys." と表示された場合は、組織のオーナーか管理者にキーの作成または自分の権限変更を依頼してください。

許可するオリジン

許可オリジンとは、公開可能キーを使用できるサイトの一覧です。SDKがキーをセッションに交換すると、ブラウザーはページのオリジンを Origin ヘッダーで送信し、Kaleidrが一覧と照合します。

空の一覧はすべてのサイトを許可します。 開発中は便利ですが、ページのソースからキーをコピーした第三者も自サイトで利用し、あなたの利用枠を消費できます。本番キーには必ず一覧を設定してください。
1件以上の一覧は登録したオリジンだけを許可します。 完全一致が必要です。https://example.com は https://www.example.com を含まず、http://localhost:3000 も http://localhost:5173 を含みません。それぞれ登録してください。

オリジンはスキーム、ホスト、任意のポートからなり、パスを含みません。

入力値	許可されるか
`https://www.example.com`	はい
`https://app.example.com:8443`	はい
`http://localhost:8000`	はい。`http` は `localhost` と `127.0.0.1` のみ許可されます。`http://[::1]` はキー管理APIから設定できますが、このページでは設定できません。
`http://www.example.com`	いいえ。ローカル以外のサイトには `https` が必要です。
`https://www.example.com/store`	いいえ。オリジンにパスは含められません。
`*.example.com`	いいえ。ワイルドカードは使用できません。`https://*.example.com` はそのまま保存され、どのサイトにも一致しません。

1つのキーに登録できるオリジンは最大100件です。

一覧を変更するには、キーの行にある編集（鉛筆）ボタンを選びます。Edit Key ダイアログで Allowed Origins を変更して Save changes を押してください。同じ画面でキーの名前も変えられます。

オリジンの追加は、そのサイトで新しく発行されるセッションから有効です。
オリジンを削除するとサイトは停止します。すでに発行されたセッションも、有効期限を待たず次のリクエストで401 Invalid or missing API key を返します。

ブロックされたサイトでの動作。 一覧にないオリジンからマウントすると、セッション交換は403 origin_not_allowed で拒否されます。レスポンスにはCORSヘッダーがないため、ブラウザーは …/b2b/v1/sdk/sessions でCORSエラーを表示し、SDKが [kaleidr:<product>] エラーを記録します。何も描画されません。正確なメッセージはトラブルシューティングを参照してください。

許可オリジンの一覧はブラウザー上でキーを使えるサイトを制限するものであり、公開可能キーを秘密にする仕組みではありません。ブラウザー以外からのリクエストは任意の Origin を送れます。セキュリティモデルで保護範囲と限界、CORSと許可オリジンで通信の詳細を説明しています。

キーのローテーションと取り消し

ローテーションすると、停止時間なしにキーの値を置き換えられます。キー行からローテーションを選び、確認します。Kaleidrは同じ種類、スコープ、許可オリジンを持つ代替キーを発行し、その値を一度だけ表示します。旧キーは24時間有効なので、新キーを展開してから切り替えられます。その間、旧キーは上限に数えられ、再ローテーションはできません。

アクセス権を持つ人が退職した場合や、組織のセキュリティポリシーに従ってローテーションしてください。漏えいしたキーは代わりに失効させます。このページでのローテーションは旧キーを24時間有効にするためです。

**失効（取り消し）**はキーを即座に無効化します。キー行の削除（ゴミ箱）操作を選び、確認します。「Revoke this API key? Any site using it will stop working immediately.」という警告が表示されます。発行済みセッションも終了するため、開いているページは次のリクエストで失敗します。失効したキーは復元できません。

サーバーキーが漏えいしたら、ローテーションではなく失効させてください。24時間の猶予期間中に漏えいした値が悪用されるおそれがあります。

テストキー

両方のキーにテスト用バリエーションがあり、kld_pk_test_… と kld_sk_test_… です。

テストキーはサンドボックスではありません。 同じAPIを呼び出し、同じ回答を受け、ライブキーと同様にAIクレジットや地図ロード数を消費します。相違点はテストキーではベースマップのタイルを読み込めないことです。

テストキーは環境の分離に役立ちます。ステージングの通信を独立したキーに紐付ければ、本番に影響せず失効できます。テスト通信が無料だと考えないでください。

API Keysページはライブキーだけを作成します。テストキーはキーAPIで "environment": "test" を指定して作成します。

管理画面では設定できないオプション

API Keysページで設定できるのは名前、種類、許可オリジンです。その他の設定は https://api.kaleidr.com/shared-api/api-keys のキーAPIから行います。

キーAPIで認証するのは利用者本人であり、APIキーではありません。ログイン済みの組織オーナーまたは管理者のアクセストークンを Authorization: Bearer として送信してください。APIキーで別のキーを作成・変更することはできません。

フィールド	種類	初期値	機能
`name`	1～200文字の文字列	必須	キーの表示名。
`org_id`	UUID	主組織	キーの所属組織。リクエスト本文に含めます。作成時のクエリ `org_id` は無視されます。
`key_type`	`"publishable"` または `"server"`	`"publishable"`	キーの種類。作成後は変更不可。
`environment`	`"live"` または `"test"`	`"live"`	ライブキーまたはテストキーを作成します。作成後は変更不可。
`scopes`	文字列の配列	`["ai", "maps", "design"]`	キーに付与するスコープ。作成後は変更不可。
`vendor_acknowledged`	真偽値	`false`	`vendor` を持つ公開可能キーの作成には `true` が必要です。
`allowed_origins`	文字列配列、最大100件	`[]`	許可オリジン。公開可能キーのみ。
`allowed_products`	文字列配列	`[]`（全製品）	`chat`、`editor`、`viewer`、`tile` の一部に制限します。すべてのキー種類に適用。下記参照。
`allowed_ips`	文字列配列、最大100件	`[]`（すべてのアドレス）	サーバーキーの利用を許可するIPアドレスまたはCIDR範囲。
`monthly_cap_tokens`	0以上の整数	なし	請求期間中にこのキーが消費できるAIクレジットの最大値。1以上で上限、`0` または `null` は無制限です。
`expires_at`	将来の日時	なし	キーの有効期限。

Freeでは scopes と allowed_products が、リクエスト内容にかかわらずプランで許可されるすべての項目（ai、maps、design、および chat、editor、viewer、tile）に設定されます。Freeでのローテーションも同様です。どのプランでも許可されないスコープや製品を要求すると403 tier_capability_not_allowed となり、黙って省略されることはありません。

製品制限はキーを使用するすべての場所で適用されます。 公開可能キーが許可されない製品をマウントしようとすると、セッション交換で403 product_not_allowed になります。製品制限のあるサーバーキーや旧形式キーも、他製品のエンドポイントへの各リクエストで403 product_not_allowed になります。チャット、場所、ジオコーディングのエンドポイントは chat、デザインのエンドポイントは editor に属します。サーバーキーからスコープが許すすべてのエンドポイントを呼びたい場合は allowed_products を空にしてください。対応表は認証とスコープにあります。

このリクエストでは、1つのステージングサイトでChatのみ利用できる公開可能テストキーを作成します。

curl -X POST https://api.kaleidr.com/shared-api/api-keys \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Staging site chat",
    "key_type": "publishable",
    "environment": "test",
    "allowed_origins": ["https://staging.example.com"],
    "allowed_products": ["chat"]
  }'

レスポンス 201 には設定内容と、1回限りの完全なキー値 plaintext_key が含まれます。

{
  "id": "5f0c2a9e-…",
  "name": "Staging site chat",
  "key_prefix": "kld_pk_test_…",
  "key_type": "publishable",
  "environment": "test",
  "scopes": ["ai", "maps", "design"],
  "allowed_origins": ["https://staging.example.com"],
  "allowed_products": ["chat"],
  "allowed_ips": [],
  "monthly_cap_tokens": null,
  "status": "active",
  "expires_at": null,
  "plaintext_key": "kld_pk_test_…"
}

自社のビジネスデータを参照できるキー

vendor スコープを持つChatは、組織が公開した業務データを使って回答できます。データのアップロードも、そのデータをキーで読み取る権限もEnterprise限定です。スコープはキーAPIからのみ付与されます。

curl -X POST https://api.kaleidr.com/shared-api/api-keys \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Site chat with our data",
    "key_type": "publishable",
    "scopes": ["ai", "vendor"],
    "vendor_acknowledged": true,
    "allowed_origins": ["https://www.example.com"]
  }'

vendor_acknowledged が必要なのは、公開可能キーがページソースに存在し、誰でもChatに質問でき、回答にアップロードデータが含まれる可能性があるためです。true を指定することで、その公開を意図していることを確認します。

公開可能キーが vendor を要求し、"vendor_acknowledged": true がなければ 422 vendor_scope_requires_acknowledgement で拒否されます。
サーバーキーに確認は必要ありません。
FreeまたはProで vendor を要求すると、vendor_acknowledged の有無にかかわらず 403 tier_capability_not_allowed になります。キーは作成されません。

自社データで、データのアップロードと回答に使用されたかの確認方法を説明しています。

キーの変更（PATCH /shared-api/api-keys/{id}）では name、allowed_origins、allowed_products、allowed_ips、monthly_cap_tokens、expires_at を受け付けます。ローテーション（POST /shared-api/api-keys/{id}/rotate）では grace_hours を0～8760で指定できます。初期値0では旧キーは即時停止します。失効は POST /shared-api/api-keys/{id}/revoke です。拒否コードはエラーを参照してください。

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

正しいキーがあるだけでは、キーを必要とする製品が表示されるとは限りません。ページ自身も2つの条件を満たす必要があり、ブラウザーのエラーから原因が明確に分からないことがあります。

1. キーで許可されたオリジンからページを配信する

開発中もHTTPまたはHTTPSでページを配信してください。 ディスクから直接開いたファイル（file://）には許可リストに追加できるオリジンがありません。
キーに許可オリジンが設定されている場合、ページのオリジンは完全に一致する必要があります。 スキーム、ホスト、ポートを含みます。ローカル開発では一般に http://localhost:<port> を追加します。

条件を満たさないと何も表示されず、コンソールにはセッション交換時のCORSエラーが出ます。ネットワーク障害のように見えますが、原因はオリジンの設定です。

2. コンテンツセキュリティポリシーで必要な読み込みを許可する

サイトが Content-Security-Policy ヘッダーを送る場合、各製品が使用するKaleidrのホストを許可する必要があります。このヘッダーがないサイトでは設定は不要です。

製品	ポリシーで許可するもの
Viewer、Tile	`https://cdn.kaleidr.com` のスクリプト、`https://map-embed.kaleidr.com` のフレーム、キー付きマウントでは `https://api.kaleidr.com` への接続
Chat、Editor	`https://cdn.kaleidr.com` のスクリプト、`https://api.kaleidr.com` への接続、両製品がページにスタイルを追加するためインラインスタイル。Editorは `https://tile.kaleidr.com` からベースマップも取得します。

製品ごとの詳細なディレクティブはコンテンツセキュリティポリシーを参照してください。

設定が間違っていると、ブラウザーは Refused to load… または Refused to connect… を記録し、遮断したアドレスとディレクティブを示します。

キーを使用する

Webページでは公開可能キーを製品に渡します。SDKがセッションに交換し、製品がマウントされている間は更新し続けます。

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

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

確認する結果： ベースマップが表示され、Networkタブの https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions が 200 を返します。クイックスタートに各製品の完全なサンプルページがあります。

サーバーからはすべてのリクエストにサーバーキーを添えます。次の呼び出しはデザインエンドポイントが認識する地図スタイルを一覧表示し、AIクレジットを消費しません。キーの動作確認に適しています。

curl https://api.kaleidr.com/inference-api/b2b/v1/design/styles \
  -H "Authorization: Bearer kld_sk_live_…"

確認する結果： styles 配列を含むJSONオブジェクトと 200 が返ります。{"detail":"Invalid or missing API key"} を伴う 401 はキーが誤っているか失効済みであることを示します。{"detail":"server_key_in_browser"} を伴う 403 は Origin ヘッダーが送られたことを示すため、取り除いてください。続きはサーバークイックスタートをご覧ください。

次のステップ

クイックスタート：Chat、Viewer、Tileの動作するページ。
Kaleidrの仕組み：セッション、組織、2種類の利用枠。
認証とスコープ：認証情報の送信方法と検証方法。
本番運用チェックリスト：サイト別のキー、許可オリジン、公開前の準備。

2 種類のキー​

プランごとに利用できる機能​

スコープ​

プラン変更時の動作​

キーを作成する​

許可するオリジン​

キーのローテーションと取り消し​

テストキー​

管理画面では設定できないオプション​

自社のビジネスデータを参照できるキー​

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

1. キーで許可されたオリジンからページを配信する​

2. コンテンツセキュリティポリシーで必要な読み込みを許可する​

キーを使用する​

次のステップ​