Obter uma chave de API
Kaleidr é uma plataforma, um SDK e um sistema de acesso — para AI, mapas e design, controlados por escopos de capacidade. Uma chave é oferecida em duas formas seguras, dependendo de onde é executada; ambas pertencem à mesma organização e utilizam a mesma cota.
| Forma | Prefixo | Onde é executada | O que faz |
|---|---|---|---|
| Publishable (navegador) | kld_pk_live_… | em HTML, no SDK, em <kaleidr-map> | Restrita por origem e segura no código-fonte da página. O SDK a troca por uma sessão de curta duração em tempo de execução. Não pode atuar como bearer de servidor nem gerenciar chaves. |
| Server (backend) | kld_sk_live_… | somente nos seus servidores | Bearer completo para chamadas servidor a servidor; lista de IPs opcional, limites e expiração. Bloqueada no navegador (rejeitada com 403 server_key_in_browser). |
As chaves legadas kld_live_… existentes continuam autenticando sem alterações.
O que cada plano permite
Esta é a política canônica plano → escopo × produto. Esta tabela é mantida igual a
B2B_TIER_API_CAPABILITIES em @kaleidr/shared-types — a mesma constante que
shared-api consulta ao criar uma chave e inference-api consulta durante a troca
de sessão — por meio de um CI drift guard, garantindo que nenhuma linha possa divergir silenciosamente
do que a plataforma realmente permite.
| Plano | Publishable | Server | Escopos permitidos | Produtos permitidos |
|---|---|---|---|---|
| Free | Sim | — (403 free_plan_publishable_only) | maps | tile |
| Pro | Sim | Sim | ai, maps, design, vendor* | chat, editor, viewer, tile |
| Enterprise | Sim | Sim | ai, maps, design, vendor* | chat, editor, viewer, tile |
* vendor requer uma confirmação explícita por chave (caso contrário, 403
vendor_scope_requires_acknowledgement).
Viewer nunca precisa de uma chave — um share id funciona como credencial. Qualquer plano (inclusive Free)
pode incorporar um Viewer sem nenhuma chave. Passar uma chave para um Viewer embed
é rejeitado com product_not_allowed.
A admissão efetiva é chave armazenada × plano atual. Se uma chave Pro
for rebaixada para Free, o servidor a troca por uma sessão no formato Free —
apenas escopo maps e produto tile. Ampliar novamente uma chave Free exige
criar uma nova chave no plano superior, não editar a existente (consulte
Errors — Key management).
Chaves de teste
As duas formas possuem uma variante test (kld_pk_test_…, kld_sk_test_…).
Uma chave de teste não é um sandbox. Ela autentica na mesma API, chama os mesmos modelos e consome a mesma franquia mensal que uma chave live. Duas coisas são diferentes:
- uma chave publishable de teste pode ser criada sem uma lista de origens permitidas, enquanto uma chave live não pode;
- uma chave de teste não pode servir tiles de mapa-base.
Use chaves de teste para manter o tráfego de staging identificável e revogável de forma independente — esse é o verdadeiro valor delas. Não as trate como gratuitas.
Criar uma chave
- Entre na sua conta e abra API Keys (kaleidr.com/api-keys) — apenas administradores da organização.
- Crie uma chave — dê um nome e escolha Browser (publishable) ou
Server. Em Pro e Enterprise, ela é criada com todas as permissões do plano
(escopos
ai,maps,design; produtoschat,editor,viewer,tile); no Free, é uma chave Browser restrita amaps/tile, e a opção Server não é oferecida. - Uma chave Browser live deve ser vinculada a pelo menos uma origem permitida — uma chave publishable live sem origens é rejeitada porque se tornaria um segredo permanente no código-fonte da página.
- Copie o valor
kld_pk_live_…/kld_sk_live_…uma única vez — ele é exibido uma vez e nunca mais é mostrado.
Dois pré-requisitos para cada incorporação
Atualmente, nenhum dos dois está documentado nas páginas dos produtos, e qualquer um deles pode bloquear uma primeira integração por conta própria.
1. Lista de origens permitidas
A troca de sessão verifica o cabeçalho Origin do navegador em relação à lista de origens permitidas
da chave. Uma divergência é rejeitada com 403 session_origin_mismatch. file://
não envia nenhum Origin — exatamente como um snippet copiado costuma ser
testado pela primeira vez — portanto, sirva todas as incorporações com chave via HTTP(S).
Atualize a lista de origens permitidas de uma chave existente usando um JWT Cognito org-admin, e não a própria chave de plataforma:
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 invalida imediatamente o cache de snapshot da chave, e remover uma
origem também encerra as sessões que já estavam vinculadas a ela — cada solicitação de sessão
verifica novamente sua origem em relação aos allowed_origins atuais da chave. Assim, a próxima
solicitação de uma origem removida é rejeitada, em vez de continuar até o fim do TTL.
Adicionar uma origem funciona no sentido oposto: permite novas sessões, mas não vincula
retroativamente as sess ões existentes.
2. CSP do cliente
A Content Security Policy da sua página deve permitir os recursos carregados por cada produto.
Consulte Content Security Policy
para uma configuração por produto — Tile e Viewer adicionam apenas o carregador do SDK e um
host de frame; Chat e Editor também precisam de 'wasm-unsafe-eval' e dos hosts
do fornecedor de mapas porque o MapLibre é executado no documento pai.
Como usar
No navegador, passe a chave publishable e o SDK a trocará por uma sessão de curta duração:
<kaleidr-map product="tile"
publishable-key="kld_pk_live_…"
style-id="kaleidr-morning"
style="height:480px"></kaleidr-map>
A partir de um servidor, envie a chave server como bearer:
Authorization: Bearer kld_sk_live_…
A chave autentica como sua organização. O uso é contabilizado na cota mensal da organização. Consulte Auth & scopes para saber o que cada escopo desbloqueia e CORS & allowed origins para conhecer a lista de origens do navegador que controla cada troca de sessão.