Obter uma chave de API

Uma chave de API identifica sua organização para o Kaleidr. Cada solicitação feita com ela, do navegador ou servidor, é autorizada conforme o plano da organização e contabilizada no consumo dela. Crie e gerencie chaves em kaleidr.com/api-keys.

Você precisa de uma chave para usar Chat, Editor, Tile e a API de servidor. Não precisa de chave para incorporar um mapa publicado usando Viewer: o ID do mapa é suficiente.

Os dois tipos de chave

Há dois tipos de chave. A escolha depende de onde o código que a utiliza é executado.

	Chave publicável	Chave de servidor
Prefixo	`kld_pk_live_…`	`kld_sk_live_…`
Onde funciona	Na página web: SDK e elemento `<kaleidr-map>`	Apenas nos seus servidores
Pode ficar visível no código da página	Sim	Não. Trate como uma senha.
Como é utilizada	O SDK troca a chave por um token de sessão de curta duração; a sessão faz as chamadas	Enviada diretamente a cada solicitação como `Authorization: Bearer` ou `X-Api-Key`
Restrições possíveis	Sites na lista de origens permitidas	Restrições definidas pela API de chaves, como lista de IPs permitidos
Planos	Free, Pro, Enterprise	Pro, Enterprise
Nome na página API Keys	Browser / Embed Key	Server Key

Use uma chave publicável em tudo que é executado no navegador do visitante. Ela foi feita para ficar visível. A proteção é a lista de origens permitidas e o fato de não poder chamar a API diretamente: se uma chave publicável for enviada diretamente a um endpoint, a chamada será recusada com 401 publishable_requires_session.

Use uma chave de servidor quando seu backend chamar o Kaleidr, por exemplo para geocodificar endereços, transmitir respostas por uma rota de API à interface ou atender um aplicativo móvel. Solicitações com cabeçalho Origin, como as de navegadores, são recusadas para chaves de servidor com 403 server_key_in_browser. O SDK também se recusa a montar o produto com essa chave antes de fazer uma solicitação. Nunca exponha uma chave de servidor em uma página web ou no binário de um aplicativo.

Ambos os tipos pertencem à mesma organização e consomem os mesmos limites. Veja Como o Kaleidr funciona para entender sessões, organizações e medição de uso.

As chaves criadas antes de existirem os dois tipos começam com kld_live_. Continuam funcionando e são enviadas diretamente, como uma chave de servidor.

O que cada plano permite

O plano da sua organização define quais tipos de chave ela pode criar, quais permissões uma chave pode ter e quais produtos ela pode montar.

Plano	Publicável	Servidor	Permissões aceitas	Produtos aceitos
Free	Sim	— (403 `free_plan_publishable_only`)	`ai`, `maps`, `design`	`chat`, `editor`, `viewer`, `tile`
Pro	Sim	Sim	`ai`, `maps`, `design`	`chat`, `editor`, `viewer`, `tile`
Enterprise	Sim	Sim	`ai`, `maps`, `design`, `vendor`*	`chat`, `editor`, `viewer`, `tile`

* vendor nunca é incluído por padrão, e só chaves Enterprise podem ter essa permissão. Veja Escopos.

Cada plano também limita quantas chaves ativas uma organização pode ter:

Plano	Chaves ativas
Free	2
Pro	10
Enterprise	25

Quando o limite é ultrapassado, a criação de uma chave é recusada com 409 key_limit_reached. Revogue uma chave para criar outra. A rotação não conta como criar uma nova, mas a chave antiga continua sendo contabilizada até acabar o período de carência.

Cinco observações sobre essa tabela:

Free permite todos os produtos de navegador. Uma organização Free pode usar Chat, Editor, Tile e Viewer no site. As respostas do Chat consomem créditos mensais de IA; depois de esgotados, as solicitações retornam 429 até o próximo ciclo de cobrança, um pacote adicional ou uma atualização do plano.
Viewer está na tabela porque o plano o permite, não porque precise de chave. Um mapa publicado pode ser incorporado sem chave em qualquer plano.
Pro oferece chaves de servidor e mais chaves. Uma organização Pro pode criar chaves para o backend e manter 10 ativas, em vez de 2, com as mesmas permissões e produtos do Free.
Respostas de IA usando dados próprios da empresa são exclusivas do Enterprise, nos dois caminhos. Proprietários e administradores Enterprise podem enviar dados empresariais nos limites previstos no contrato, e o assistente do Kaleidr Studio os utiliza para membros conectados. Free e Pro não podem enviá-los. O acesso por API ou SDK com escopo vendor também é exclusivo do Enterprise. Criar uma chave com vendor no Free ou Pro é recusado com 403 tier_capability_not_allowed. Veja Seus dados.
Todo plano permite adicionar datasets a mapas no Kaleidr Studio. Usuários conectados enviam planilhas e arquivos geográficos pelo painel Data. No Free, os limites são 50.000 linhas por dataset, 32 MiB por arquivo e 250.000 linhas no total da organização. No Pro, são 100.000 linhas, 64 MiB e 5.000.000 de linhas. Enterprise usa os mesmos limites por dataset e arquivo do Pro (100.000 linhas e 64 MiB), mas o total da organização depende do contrato. Esses dados são desenhados no mapa, no Studio e em mapas publicados e podem ser usados pelo assistente de IA do Studio; não são consultados por uma chave de API. Veja Datasets no mapa.

Preços e cotas estão na página de preços. As cotas Enterprise são personalizadas e definidas em contrato.

Escopos

Um escopo é uma permissão associada à chave. Cada produto ou endpoint verifica o escopo necessário.

Escopo	O que permite	Em uma nova chave
`ai`	Chat e endpoints de chat, locais e geocodificação da API do servidor	Incluído
`maps`	Sessões de mapa base do Tile	Incluído
`design`	Editor e endpoints de design da API do servidor	Incluído
`vendor`	Permite que respostas do Chat usem dados empresariais publicados da sua organização	Não incluído; deve ser solicitado. Apenas Enterprise.

Chaves criadas na página API Keys sempre incluem ai, maps e design. Não há seleção de escopos nessa página. Para criar uma chave com vendor (só Enterprise), ou retirar um escopo padrão, use a API de chaves.

Os escopos são fixados na criação. Não podem ser editados depois, e a rotação os preserva, com duas exceções: um escopo não permitido pelo plano atual é omitido da chave substituta e, no Free, a substituta recebe todos os escopos Free (veja Quando o plano muda). Para alterar escopos, crie uma chave nova e revogue a antiga.

Quando seu plano muda

O que uma chave pode fazer é a interseção entre suas permissões e o que seu plano atual admite, conferida em cada solicitação.

De Enterprise para Pro ou Free. As chaves existentes continuam funcionando. Uma chave com vendor mantém o escopo armazenado, mas ele deixa de valer: as respostas não usam mais seus dados empresariais e nenhum erro é exibido. As solicitações continuam sendo respondidas pelo conhecimento geral. Sessões de navegador anteriores à mudança são encerradas: a próxima solicitação devolve 401 e o SDK obtém uma nova sessão no novo plano. No Pro, a rotação dessa chave devolve outra sem vendor, mantendo escopos restantes e a lista de produtos. O envio de dados empresariais passa a ser recusado com 403 vendor_data_not_on_plan. Proprietários e administradores ainda podem listar, despublicar e excluir releases anteriores.

Ao mudar para Free. Uma organização Free não pode criar chaves de servidor nem rotacionar chaves de servidor ou legadas que já possui: 403 free_plan_publishable_only. Rotacionar uma chave publicável no Free cria uma substituta com todas as permissões (ai, maps, design e os quatro produtos), independentemente da chave antiga. Os datasets já adicionados aos mapas Studio permanecem; novos envios respeitam os limites de datasets do Free. Sessões de navegador anteriores são encerradas e o SDK obtém outras.

Ao voltar para um plano superior, os recursos permitidos são restaurados. Uma chave que ainda armazena vendor volta a acessar os dados no Enterprise. Uma substituta rotacionada em plano inferior não recupera esse escopo; crie uma chave nova.

Criar uma chave

Você deve ser proprietário ou administrador da organização.

Entre em kaleidr.com e abra kaleidr.com/api-keys. As chaves da sua organização aparecem em Your API Keys.
Escolha Create Key. Abre-se o diálogo Create a Key com três campos.
Key Name. Informe um nome como Production site. Visitantes não o veem. Nomeie as chaves conforme o local de uso para identificá-las ao revogar alguma.
Key Type. Selecione Browser / Embed Key (publicável) ou Server Key. No Free, a opção Server Key não aparece. O tipo não pode ser alterado depois.
Allowed Origins. Para uma chave publicável, informe os sites permitidos separados por vírgula, como https://www.example.com, https://app.example.com. Deixe vazio para permitir qualquer site. Veja Origens permitidas para o formato. Uma chave de servidor não é vinculada a site, portanto deixe vazio.
Escolha Create Key.
Copie a chave agora. O diálogo mostra a chave completa apenas uma vez, com o aviso “Copy this key now — it won't be shown again”. Clique em Copy, guarde o valor e escolha Done. O Kaleidr não armazena a chave completa; se perdê-la, rotacione a chave para receber outra.

Resultado esperado: a tabela exibe a chave nova, com os primeiros caracteres em Key, nome, tipo (Browser ou Server), status Active e a data de hoje.

Se a página mostrar "You must be an organization admin to manage API keys.", peça a um proprietário ou administrador para criar a chave ou alterar sua função.

Origens permitidas

Origens permitidas são os sites em que uma chave publicável pode funcionar. Ao trocá-la por uma sessão, o navegador envia a origem da página no cabeçalho Origin, comparado pelo Kaleidr com a lista.

Uma lista vazia permite todos os sites. É prático no desenvolvimento, mas quem copiar a chave do código da página poderá utilizá-la no próprio site e gastar sua cota. Configure uma lista em cada chave de produção.
Uma lista com ao menos uma entrada permite apenas os sites listados. A correspondência é exata: https://example.com não inclui https://www.example.com, e http://localhost:3000 não inclui http://localhost:5173. Cadastre cada origem.

Uma origem contém protocolo, host e porta opcional, sem caminho:

Entrada	Aceita
`https://www.example.com`	Sim
`https://app.example.com:8443`	Sim
`http://localhost:8000`	Sim. `http` só é permitido para `localhost` e `127.0.0.1`. `http://[::1]` pode ser configurado pela API de gerenciamento de chaves, mas não por esta página.
`http://www.example.com`	Não. Sites não locais precisam de `https`.
`https://www.example.com/store`	Não. Uma origem não tem caminho.
`*.example.com`	Não. Não existem curingas. `https://*.example.com` é salvo literalmente e não corresponde a site algum.

Uma chave pode ter no máximo 100 origens.

Para alterar a lista, clique no ícone de edição (lápis) na linha da chave. No diálogo Edit Key, altere Allowed Origins e escolha Save changes. Também é possível renomear a chave nesse diálogo.

Adicionar uma origem vale para novas sessões criadas nesse site.
Remover uma origem bloqueia o site. Sessões já emitidas para páginas nessa origem falham na próxima solicitação com 401 Invalid or missing API key, sem aguardar a expiração.

O que acontece em um site bloqueado. Quando uma página de uma origem não listada tenta montar um produto, a troca é recusada com 403 origin_not_allowed. A resposta não contém cabeçalhos CORS, então o navegador mostra erro CORS em …/b2b/v1/sdk/sessions, o SDK registra um erro [kaleidr:<product>] e nada é exibido. Veja o texto exato em Solução de problemas.

A lista restringe de quais sites uma chave funciona no navegador, mas não a torna secreta: solicitações fora de navegadores podem enviar qualquer valor no cabeçalho Origin. O Modelo de segurança explica o alcance dessa proteção; CORS e origens permitidas detalha as solicitações.

Rotacionar e revogar

Rotacione uma chave para substituí-la sem interromper o serviço. Selecione a ação de rotação na linha e confirme. O Kaleidr cria uma nova chave com o mesmo tipo, escopos e origens permitidas, exibida uma única vez. A chave antiga continua funcionando por 24 horas para você implantar a nova antes da desativação. Durante esse prazo, ela conta para o limite do plano e não pode ser rotacionada outra vez.

Rotacione quando alguém com acesso à chave sair da equipe ou conforme sua política de segurança. Se a chave vazar, revogue-a: rotacionar nesta página deixa o valor antigo funcionando por 24 horas.

Revogue uma chave para desativá-la imediatamente. Escolha a ação de exclusão (lixeira) e confirme. O aviso diz: “Revoke this API key? Any site using it will stop working immediately.” A revogação encerra todas as sessões criadas pela chave, então páginas abertas falham na próxima solicitação. Uma chave revogada não pode ser recuperada.

Quando uma chave de servidor vazar, revogue em vez de rotacionar: o período de carência de 24 horas manteria o valor comprometido funcionando.

Chaves de teste

Ambos os tipos possuem variantes de teste: kld_pk_test_… e kld_sk_test_….

Uma chave de teste não é um sandbox. Ela chama a mesma API, recebe as mesmas respostas e consome os mesmos créditos de IA e carregamentos de mapas de uma chave real. A única diferença é que não carrega tiles do mapa base.

A vantagem da chave de teste é separar o tráfego do ambiente de homologação em sua própria chave, que pode ser revogada sem afetar a produção. Não presuma que testes são gratuitos.

A página API Keys cria apenas chaves ativas. Para uma chave de teste, use a API de chaves com "environment": "test".

Opções não disponíveis na página

Na página API Keys é possível definir nome, tipo e origens permitidas. A API de chaves oferece outras opções em https://api.kaleidr.com/shared-api/api-keys.

A API de chaves autentica você, e não uma chave: envie o token de acesso de um proprietário ou administrador conectado como Authorization: Bearer. Uma chave de API não pode criar ou alterar outras chaves.

Campo	Tipo	Padrão	Função
`name`	string, 1–200 caracteres	obrigatório	Nome da chave.
`org_id`	UUID	sua organização principal	Organização que recebe a chave. Envie no corpo: uma consulta `org_id` é ignorada na criação.
`key_type`	`"publishable"` ou `"server"`	`"publishable"`	Tipo da chave, fixo após a criação.
`environment`	`"live"` ou `"test"`	`"live"`	Cria chave ativa ou de teste. Depois não muda.
`scopes`	array de strings	`["ai", "maps", "design"]`	Escopos atribuídos à chave, fixos após a criação.
`vendor_acknowledged`	booleano	`false`	Deve ser `true` para criar uma chave publicável com `vendor`.
`allowed_origins`	array de strings, até 100	`[]`	Origens permitidas. Só chaves publicáveis.
`allowed_products`	array de strings	`[]` (todos os produtos)	Restringe a chave a alguns de `chat`, `editor`, `viewer`, `tile`. Vale para todos os tipos: veja nota abaixo.
`allowed_ips`	array de strings, até 100	`[]` (qualquer endereço)	IPs ou intervalos CIDR aceitos para uma chave de servidor.
`monthly_cap_tokens`	inteiro, 0 ou mais	nenhum	Máximo de créditos de IA por ciclo de cobrança da chave. Valor 1 ou maior impõe teto; `0` ou `null` não impõe limite.
`expires_at`	data e hora futuras	nenhuma	Quando a chave deixa de funcionar.

No Free, scopes e allowed_products são sempre definidos para todas as opções do plano (ai, maps, design; chat, editor, viewer, tile), independentemente do que a solicitação pedir, inclusive na rotação. Em todos os planos, pedir um escopo ou produto não autorizado gera 403 tier_capability_not_allowed; nenhuma opção é descartada silenciosamente.

O limite de produtos vale em todo uso da chave. Uma chave publicável limitada a certos produtos é recusada com 403 product_not_allowed na troca de sessão se a página tentar montar outro produto. Chaves de servidor e legadas também recebem 403 product_not_allowed em cada chamada a endpoint de outro produto: endpoints de chat, lugares e geocodificação pertencem a chat, e os de design pertencem a editor. Para permitir todos os endpoints previstos nos escopos de uma chave de servidor, deixe allowed_products vazio. Veja a tabela em Autenticação e escopos.

Esta solicitação cria uma chave publicável de teste limitada ao Chat em um único site de homologação:

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"]
  }'

A resposta 201 inclui as configurações e, uma única vez, o valor integral em 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_…"
}

Uma chave que pode acessar seus dados empresariais

O escopo vendor permite que respostas de Chat usem os dados empresariais publicados pela sua organização. Tanto enviar esses dados quanto ter uma chave que os leia são recursos exclusivos do Enterprise. O escopo só pode ser concedido pela API de chaves:

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 existe porque uma chave publicável fica no código-fonte da página: qualquer visitante pode fazer perguntas, e as respostas podem incluir seus dados enviados. Definir o campo como true registra que você pretende permitir isso.

Uma chave publicável que solicita vendor sem "vendor_acknowledged": true é recusada com 422 vendor_scope_requires_acknowledgement.
Chaves de servidor não precisam dessa confirmação.
No Free e no Pro, qualquer solicitação com vendor é recusada com 403 tier_capability_not_allowed, com ou sem vendor_acknowledged. Nenhuma chave é criada.

Seus dados explica o envio e como verificar que uma resposta os usou.

Alterar uma chave (PATCH /shared-api/api-keys/{id}) aceita name, allowed_origins, allowed_products, allowed_ips, monthly_cap_tokens e expires_at. Rotacionar (POST /shared-api/api-keys/{id}/rotate) aceita grace_hours de 0 a 8760; no padrão 0 a chave anterior é desativada imediatamente. Revogar usa POST /shared-api/api-keys/{id}/revoke. Os códigos de erro estão em Erros.

Dois pré-requisitos para cada incorporação

Uma chave correta não basta para renderizar um produto que exige autenticação. A página também precisa atender a dois requisitos, cujas falhas nem sempre são esclarecidas pelos erros do navegador.

1. A página é servida por uma origem permitida pela chave

Sirva a página por HTTP ou HTTPS, mesmo no desenvolvimento. Arquivos abertos diretamente (file://) não têm uma origem que possa ser permitida na chave.
Se a chave lista origens permitidas, a origem da página precisa estar exatamente na lista: protocolo, host e porta. Para desenvolvimento local, geralmente http://localhost:<port>.

Se isso estiver errado, nada aparece e o console mostra erro CORS na troca de sessão. Parece um problema de rede, mas a causa é a lista de origens.

2. A Política de Segurança de Conteúdo permite carregar o produto

Se seu site envia o cabeçalho Content-Security-Policy, ele precisa permitir os hosts do Kaleidr usados por cada produto. Se não envia esse cabeçalho, nenhuma configuração é necessária.

Produto	O que a política precisa permitir
Viewer, Tile	Scripts de `https://cdn.kaleidr.com`, iframe de `https://map-embed.kaleidr.com` e, para montagem com chave, conexão com `https://api.kaleidr.com`
Chat, Editor	Scripts de `https://cdn.kaleidr.com`, conexões com `https://api.kaleidr.com` e estilos inline, pois ambos adicionam estilos à página. Editor também carrega o mapa base de `https://tile.kaleidr.com`.

Política de segurança de conteúdo lista as diretivas completas para cada produto.

Se a política estiver errada, o navegador registra Refused to load… ou Refused to connect…, informando o endereço bloqueado e a diretiva correspondente.

Usar a chave

Em uma página web, forneça uma chave publicável ao produto. O SDK troca por uma sessão e mantém a sessão atualizada enquanto o produto estiver montado.

<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>

Resultado esperado: o mapa base é exibido e a aba Network mostra uma resposta 200 de https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions. O Início rápido traz uma página completa de cada produto.

A partir de um servidor, envie a chave de servidor em toda solicitação. Esta chamada lista os estilos de mapa conhecidos pelos endpoints de design sem gastar créditos de IA, sendo um bom primeiro teste.

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

Resultado esperado: 200 com um objeto JSON contendo o array styles. 401 com {"detail":"Invalid or missing API key"} significa valor errado ou chave revogada. 403 com {"detail":"server_key_in_browser"} indica que a solicitação enviou o cabeçalho Origin; remova-o. Continue em Início rápido de servidor.

Próximas etapas

Início rápido: uma página funcional para Chat, Viewer e Tile.
Como o Kaleidr funciona: sessões, organizações e os dois grupos de consumo.
Autenticação e escopos: como cada credencial é enviada e verificada.
Checklist de produção: uma chave por site, origens permitidas e demais preparativos.

Os dois tipos de chave​

O que cada plano permite​

Escopos​

Quando seu plano muda​

Criar uma chave​

Origens permitidas​

Rotacionar e revogar​

Chaves de teste​

Opções não disponíveis na página​

Uma chave que pode acessar seus dados empresariais​

Dois pré-requisitos para cada incorporação​

1. A página é servida por uma origem permitida pela chave​

2. A Política de Segurança de Conteúdo permite carregar o produto​

Usar a chave​

Próximas etapas​