Pular para o conteúdo principal

CORS e origins permitidas

Chaves Publishable (kld_pk_live_…) possuem uma lista allowed-origins — os browser origins autorizados a usar a chave. Defina-a ao criar a chave (por exemplo, https://acme.com, https://app.acme.com); uma live publishable key requer pelo menos uma. Chaves Server (kld_sk_live_…) não recebem permissão CORS, portanto uma página nunca pode ler uma resposta feita com uma delas. Observe o que isso cobre e o que não cobre: CORS bloqueia a resposta, não a solicitação — uma server key embutida no código fonte já foi exposta independentemente disso. Por isso o SDK rejeita kld_sk_… no mount; server keys são apenas server-to-server.

Como é aplicado​

  • Preflight (OPTIONS) é permissivo — ele reflete a origin solicitada para que o navegador prossiga (a chave não é apresentada em um preflight).
  • A solicitação real só recebe um header Access-Control-Allow-Origin quando o Origin da solicitação está na lista permitida da chave. Uma origin fora da allowlist não recebe header ACAO, portanto o navegador bloqueia a resposta.

Não há cookies envolvidos — a platform API usa autenticação bearer-token, portanto não existe Access-Control-Allow-Credentials.

Publishable keys viajam em URLs para o tile CDN​

tile.kaleidr.com recebe sua publishable key como query parameter ?key=. Isso é intencional e tem uma consequência importante: query strings são registrados nos access logs do CDN, no histórico do navegador e em qualquer proxy intermediário.

Isso é aceitável porque uma publishable key é pública por construção — ela já é enviada no código-fonte da sua página. O controle que a torna segura é a origin allowlist por chave, aplicada pelo edge em cada tile request, além da restrição da chave ao scope maps.

Isso não é aceitável para uma server key. Nunca coloque kld_sk_… em uma URL e observe que uma server key vazada já está exposta quando a API a recusa.

Em todos os outros lugares — SDK session exchange, platform API — a chave viaja como header, nunca como query parameter.

Dicas​

  • Use bare origins (scheme://host[:port]) — sem path e sem barra final — para corresponder exatamente ao header Origin do navegador.
  • https é obrigatório, exceto para localhost / 127.0.0.1 (testes locais).
  • Chamadas server-to-server com uma chave server (sem browser Origin) não são limitadas por CORS, mas continuam autenticando e verificando scopes normalmente.
  • Server keys também aceitam uma IP allowlist opcional — uma chamada de um IP fora da lista é rejeitada com 403 ip_not_allowed, mesmo quando o bearer é válido. Gerencie em kaleidr.com/api-keys.