認証とスコープ
platform API は組織の key で認証します。形式は2種類です — 同じ org、同じ scopes、異なる runtime：
| Form | Credential | Sent as |
|---|---|---|
| Server (backend) | kld_sk_live_… | Authorization: Bearer … または X-Api-Key |
| Publishable (browser) | kld_pk_live_… | SDK が短期間有効な session と交換。raw bearer としては送信しない |
Authorization: Bearer kld_sk_live_…
# or
X-Api-Key: kld_sk_live_…
Server key は backend から各 request ごとに送信する bearer です。
Publishable key は browser 用です。SDK が runtime に短期間有効で
origin-bound の session token と交換するため、publishable key 自体が
page source 内で継続的な credential になることはありません。publishable key を直接
bearer として提示すると拒否されます — SDK 経由で使用してください。server key には CORS
grant がありません。そのため page は server key を使った response を 読む ことはできません —
ただし CORS は request が browser から外へ送信されること自体は止められないため、server key を page
source に貼り付けた時点ですでに漏洩しています。API が拒否する時点では手遅れです。
このため SDK は mount 時に kld_sk_… key を拒否します。server key は必ず
server-side に保持してください。
既存の legacy kld_live_… key は両方で direct bearer として引き続き動作します。
Scopes
key は capability scope を持ちます。各 route family には1つ必要です：
| Scope | Route family | Used by |
|---|---|---|
ai | /inference-api/b2b/v1/chat/*, /retrieval/* | chat embed |
design | /inference-api/b2b/v1/design/* | editor embed |
maps | designed basemaps | the tile embed |
vendor | (modifier, not a route) | the chat embed, on your own data |
デフォルトでは Pro/Enterprise key は ai、design、maps で mint されます。
Free-plan key は maps + tile product のみに制限されます。正式な
plan × scope × product table は
APIキーを取得 を参照してください。
Effective admission = stored key × current tier. Runtime session-exchange は
call ごとに admission を再計算するため、Pro-tier key が Free に downgrade されると、
その時点以降は tile session のみ mint されます — stored key に
ai と design の制限が残っていても同様です。rejection subcode は
2つのケースを区別します：
insufficient_scope— key はその capability を 一度も 持っていなかった。tier_capability_not_allowed— key は 持っていた が current tier が 許可しなくなった。復元するには plan を upgrade してください。
stored key の空の allowed_products は すべて の product を意味します
（none ではありません）。tier はその superset を plan が許可する範囲までさらに狭めます。
vendor — 意図して要求し、必要な場所だけで使う
vendor は route gate ではありません。request の許可/拒否を決めるのではなく、
AI chat が回答時に 組織が upload した vendor data を参照できるかどうかを決めます。
他の scope はすべて「この key はこの endpoint を呼べるか」を表しますが、vendor は
「この key は内部データを使って回答してよいか」を表します。
そのため デフォルトでは決して含まれません — mint 時に明示的に要求してください：
{ "name": "our-site-widget", "scopes": ["ai", "vendor"] }
どの key に vendor を持たせるかがセキュリティ判断そのものです。 chat embed は
browser widget です。publishable key を短期間有効な session に交換するため、
vendor-enabled key は必然的に public page 内にあります。property list、営業時間、
公開 rate のように、すべての visitor に見せてもよい data なら問題ありません。
公開したくないものには 不適切です。exchange を保護する origin
allowlist は browser convention であり confidentiality boundary ではありません。
独自に Origin header を設定できる caller はそれでは止まりません。
したがって：
- surface ごとに1つの key。 Marketing site、demo page、customer-facing
app で key を共有しないでください。自社 data から回答する必要がある surface のみに
vendorを付けます。 - rate sheet、cost basis、未公開情報を publishable key の背後に置かないでください。 public page に表示されると困る回答なら、その data は vendor-scoped embed に置くべきではありません。
- Session は product に絞り込まれます。そのため parent key に
vendorがあってもtileまたはviewersession がvendorを持つことはありません。
取り消すには、key の scopes を編集するか revoke してください — どちらも 次の request から有効で、すでに進行中の session にも適用され ます。session expiry まで 延期されることはありません。
401 と 403
意図的に区別されています：
- 401 Unauthorized — key がない / invalid / revoked / expired。key 値と
revoke されていないことを再確認してください。publishable key が raw bearer として送られた場合の
publishable_requires_sessionも含みます。 - 403 Forbidden — key は存在するが、この場所では許可されていません。一般的な
subcode：
insufficient_scope（最初から持っていない）、tier_capability_not_allowed（持っていたが tier が許可しなくなった）、session_origin_mismatch、ip_not_allowed（server key）、server_key_in_browser、product_not_allowed。
どちらも fail closed です。scope がない key はすべての場所で拒否されます。
Session token
SDK が publishable key と交換する session は次のような形式です：
kld_sess_{env}_{jwt}
例：kld_sess_live_eyJhbGciOi…。runtime call では
Authorization: Bearer または X-Api-Key として提示します。Default TTL は900秒（15
分）、server max は30分です。session は mint された product に絞り込まれ、
すべての request で parent key の live policy が再読込されます。
取り消しは即時、新規 grant は即時ではありません。 この2方向は意図的に 非対称で、fail closed です：
| Change to the parent key | Effect on a session already in flight |
|---|---|
| Revoked or deleted | 次の request で拒否 |
| A scope removed | 次の request で削除 |
| Plan downgraded | tier-gated capability は次の request で拒否 |
| Rate limit or monthly cap set to a new value | 次の request で適用 |
| A scope added, plan upgraded, or a limit lifted entirely | 見えない — 新しい session を mint |
session は parent より狭めることしかできず、mint 時の scope を超えて広げることはできません。 したがって新しい grant には新しい exchange が必要です。session が短い（default 15分）のは この差を小さくするためです。
完全な status table は Errors を参照してください。