Autenticação de API de mapas

Um design seguro separa credenciais por ambiente de execução. O navegador precisa de uma credencial segura para exposição e estritamente limitada a origens e capacidades aprovadas. O backend precisa de um segredo que nunca entre no código cliente e autorize operações servidor a servidor. Não devem ser intercambiáveis. Limite âmbitos, separe ambientes, monitorize uso, rode credenciais e distinga falhas de autenticação das de autorização. A Kaleidr implementa isto com chaves publicáveis (kld_pk_live_…) e chaves de servidor (kld_sk_live_…).

As secções seguintes abrangem credenciais de navegador e servidor, origens, CORS, âmbitos, ciclo de vida, limites de confiança multi-inquilino e erros comuns. Consulte a documentação para programadores. Para a arquitetura SDK, veja O que é um SDK de mapas com IA?. Para incorporação e chat, veja Como incorporar um mapa interativo e Chat de IA no Mapbox, Google Maps e MapLibre.

Elementos essenciais

• Primeiro o ambiente: credenciais do navegador são feitas para exposição; as do servidor para segredo.
• Origem ≠ autenticação: CORS e origens permitidas não substituem a verificação.
• Âmbito ≠ inquilino: âmbitos de capacidade não são autorização de utilizador ou linha.
• Rotação segura: implemente a substituição antes de revogar uma chave ativa.
• Oculte nos registos: registe IDs e estados, nunca valores de credenciais.

Por que é diferente no navegador?

O navegador é um ambiente não fiável. Tudo o que recebe pode normalmente ser inspecionado na fonte, ferramentas de programação, pedidos de rede, JavaScript empacotado, armazenamento ou objetos em execução. Colocar um segredo duradouro no cliente—React, variáveis Next.js NEXT_PUBLIC_*, Vite VITE_*, HTML, webviews móveis ou JSON frontend—é inseguro porque o navegador não o pode esconder de quem o executa. Pergunte o que a credencial pode fazer e onde pode correr, não onde escondê-la no bundle.

Os nomes variam, mas o padrão é comum. A Kaleidr usa chaves publicáveis e de servidor (Auth & Scopes). O Mapbox distingue âmbitos públicos e secretos e exige pedidos com tokens secretos no servidor (Usar Mapbox com segurança). A Google Maps Platform usa restrições de aplicação e API e recomenda proteger credenciais de serviços Web, com OAuth 2.0 quando suportado entre servidores (Orientações de segurança). Credenciais cliente devem ser concebidas para exposição; as do servidor, para segredo.

Como funcionam as chaves da Kaleidr?

A documentação atual define duas formas no mesmo sistema de organização e capacidades. Chaves publicáveis usam kld_pk_live_… em HTML, SDK, <kaleidr-map> e integrações Web. O SDK troca a chave por uma sessão breve vinculada à origem, em vez de usar a cadeia como bearer permanente. Chaves de servidor usam kld_sk_live_… apenas em servidores fiáveis, normalmente como Authorization: Bearer … ou X-Api-Key: …. São bloqueadas no navegador e não recebem permissão CORS (CORS & Allowed Origins). Nunca coloque uma chave de servidor no cliente nem trate uma variável pública como armazenamento secreto.

Origens permitidas devem ser origens simples, sem caminho nem barra final: https://app.example.com, não https://app.example.com/maps. A Kaleidr exige HTTPS, exceto em testes locais em localhost ou 127.0.0.1. A correspondência exata importa: raiz, www, app, admin e pré-visualização são origens distintas. A restrição reduz reutilização indevida, mas não substitui manter segredos fora do cliente.

Como diferem CORS, autenticação, âmbito e autorização?

CORS controla se o navegador pode ler uma resposta entre origens. Autenticação identifica o chamador. O âmbito determina se a credencial pode usar uma capacidade. A autorização da aplicação anfitriã decide que utilizador ou inquilino acede a registos privados. A Kaleidr pode aceitar preflight, mas só devolve Access-Control-Allow-Origin para uma origem autorizada; chaves de servidor não recebem CORS. 401 costuma indicar credencial ausente, inválida, expirada ou revogada. 403 indica credencial válida sem permissão; a Kaleidr usa insufficient_scope quando falta a capacidade da rota. Trate-os separadamente no diagnóstico e monitorização.

Como criar, guardar, rodar e revogar credenciais?

Aplique menor privilégio: conceda apenas os âmbitos necessários. O Mapbox recomenda âmbitos mínimos e apenas públicos no navegador; a Google recomenda restrições de aplicação e API limitadas às APIs usadas. Não partilhe uma credencial entre desenvolvimento, pré-visualização e produção. Chaves separadas reduzem o raio de impacto e tornam a rotação mais segura. O Mapbox recomenda tokens por ambiente ou cliente; a Google, chaves por aplicação (Gestão de tokens).

Novas chaves Kaleidr são mostradas uma vez; copie-as imediatamente para um gestor de segredos. Guarde chaves de servidor num gestor ou ambiente protegido, nunca em repositórios públicos ou bundles. Em CI/CD, injete segredos na implementação, mascare-os nos registos e evite imprimir o ambiente. Registe ID, estado e origem; oculte cabeçalhos e valores. Para rodar, crie e restrinja uma substituição, implemente, verifique tráfego e só depois revogue a anterior—mais depressa se comprometida. Quotas também controlam segurança: uso é medido por organização e streaming limita concorrência (Quota & Rate Limits). Trate 429 de forma diferente de 401 e 403; aplique espera progressiva.

// Unsafe: never ship a server key to the browser
const SERVER_KEY = "YOUR_KALEIDR_SERVER_KEY";

// Safer browser pattern: publishable key + SDK session exchange
Kaleidr.mount("#map", {
  publishableKey: "kld_pk_live_REPLACE_ME"
});

// Safer backend pattern: server key stays on the host
const response = await fetch("https://api.example.com/resource", {
  headers: {
    Authorization: `Bearer ${process.env.KALEIDR_SERVER_KEY}`
  }
});

Como separar autenticação da plataforma e da aplicação?

O padrão recomendado usa no navegador uma chave publicável para funções públicas do SDK através de uma origem aprovada; pedidos autenticados seguem para o backend. Este gere identidade, pertença ao inquilino, autorização de objetos, dados privados e chave de servidor num gestor, chama a plataforma servidor a servidor e devolve apenas campos aprovados. Chaves publicáveis não autenticam utilizadores; chaves de servidor não autorizam linhas da base de dados. Segundo a documentação, um mapa Viewer publicado é protegido por ligação partilhada e não exige chave. Ainda assim, trate a ligação como controlo de acesso e não envie dados privados por uma vista pública irrestrita. CSP e HTML seguro são complementares; o Mapbox alerta para XSS por HTML não fiável em pop-ups e recomenda texto.

Que erros devem ser evitados?

Em falhas no navegador, verifique origem, HTTPS, tipo de chave, âmbito e ordem de troca antes de assumir indisponibilidade. No servidor, verifique tipo, ambiente, âmbito, injeção e revogação acidental.

Veredito final

A segurança começa com uma decisão: não usar o mesmo modelo no navegador e backend. O navegador requer credenciais exponíveis limitadas por origem, âmbito, duração ou controlos equivalentes; o backend exige segredos em infraestrutura fiável. Acrescente menor privilégio, isolamento, autorização, monitorização e rotação. A Kaleidr segue o padrão: chaves publicáveis são limitadas por origem e trocadas por sessões breves; chaves de servidor são bearer para chamadas servidor a servidor e bloqueadas no navegador. Essa fronteira é mais importante do que tentar esconder uma chave no frontend.

Proteja a sua API com a documentação Kaleidr

Reveja tipos de chave, âmbitos, regras de origem e comportamento antes da implementação. Leia Kaleidr Auth & Scopes e continue na documentação para programadores para SDK e rotas da Platform API.

Perguntas frequentes

O que é autenticação de API de mapas?

É o mecanismo que identifica a aplicação ou serviço que acede a APIs de mapas, locais, mosaicos, rotas ou dados espaciais. Inclui chaves, tokens, sessões, bearer e OAuth.

Uma chave API pode ser usada com segurança no navegador?

Só se o fornecedor a conceber para cliente. Deve ter restrições de origem, âmbitos públicos, aplicação ou sessão breve. Um segredo de servidor nunca deve aparecer no navegador.

Uma chave publicável é secreta?

Não. A segurança não deve depender de ocultar a cadeia, embora exija restrições e monitorização.

Uma chave de servidor é secreta?

Sim. Deve permanecer no backend e não aparecer em HTML, bundles JavaScript, webviews, repositórios públicos ou armazenamento cliente.

CORS é autenticação?

Não. CORS controla a leitura entre origens; autenticação identifica o chamador e autorização define o que pode fazer.

Qual é a diferença entre 401 e 403?

401 costuma significar credencial ausente, inválida, expirada ou revogada. 403 significa credencial válida sem permissão.

Devo separar chaves de desenvolvimento e produção?

Sim. Reduz o raio de impacto, simplifica restrições, melhora visibilidade e torna a rotação mais segura.

Como rodo uma chave API?

Crie e restrinja uma substituição, implemente, verifique tráfego e só então revogue a anterior. Acelere se houver comprometimento.

O Kaleidr Viewer exige chave API?

A documentação atual indica que mapas Viewer publicados são protegidos por ligação partilhada e não exigem chave.

Como protege a Kaleidr as integrações Web?

Usa uma chave publicável com lista de origens; o SDK troca-a por sessão breve vinculada à origem. Chaves de servidor são bloqueadas no navegador e destinadas a chamadas entre servidores.

Referências

• IETF. HTTP Semantics (RFC 9110). RFC Editor. Consultado a 17 de agosto de 2026. https://www.rfc-editor.org/rfc/rfc9110

• IETF. The OAuth 2.0 Authorization Framework: Bearer Token Usage (RFC 6750). RFC Editor. Consultado a 17 de agosto de 2026. https://www.rfc-editor.org/rfc/rfc6750

• WHATWG. Fetch Standard. Consultado a 17 de agosto de 2026. https://fetch.spec.whatwg.org/#http-cors-protocol

• Google. Orientações de segurança da Google Maps Platform. Documentação Google Maps Platform. Consultado em 17 de agosto de 2026. https://developers.google.com/maps/api-security-best-practices

• Kaleidr. Auth & Scopes. Documentação para programadores. Consultado em 17 de agosto de 2026. https://docs.kaleidr.com/platform-api/auth-and-scopes

• Kaleidr. CORS & Allowed Origins. Documentação para programadores. Consultado em 17 de agosto de 2026. https://docs.kaleidr.com/platform-api/cors-and-allowed-origins

• Kaleidr. Quota & Rate Limits. Documentação para programadores. Consultado em 17 de agosto de 2026. https://docs.kaleidr.com/platform-api/quota-and-rate-limits

• Mapbox. Usar Mapbox com segurança. Documentação Mapbox. Consultado em 17 de agosto de 2026. https://docs.mapbox.com/help/dive-deeper/how-to-use-mapbox-securely/

• Mapbox. Gestão de tokens. Documentação Mapbox. Consultado em 17 de agosto de 2026. https://docs.mapbox.com/accounts/guides/tokens/

@misc{ietf_rfc9110_2026,
  title  = {HTTP Semantics (RFC 9110)},
  author = {{IETF}},
  note   = {Accessed 17 August 2026},
  url    = {https://www.rfc-editor.org/rfc/rfc9110}
}

@misc{ietf_rfc6750_2026,
  title  = {The OAuth 2.0 Authorization Framework: Bearer Token Usage (RFC 6750)},
  author = {{IETF}},
  note   = {Accessed 17 August 2026},
  url    = {https://www.rfc-editor.org/rfc/rfc6750}
}

@misc{whatwg_fetch_cors_2026,
  title  = {Fetch Standard},
  author = {{WHATWG}},
  note   = {CORS protocol; accessed 17 August 2026},
  url    = {https://fetch.spec.whatwg.org/#http-cors-protocol}
}

@misc{kaleidr_auth_scopes_2026,
  title  = {Auth and Scopes},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 17 August 2026},
  url    = {https://docs.kaleidr.com/platform-api/auth-and-scopes}
}

@misc{kaleidr_cors_origins_2026,
  title  = {CORS and Allowed Origins},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 17 August 2026},
  url    = {https://docs.kaleidr.com/platform-api/cors-and-allowed-origins}
}

@misc{kaleidr_quota_2026,
  title  = {Quota and Rate Limits},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 17 August 2026},
  url    = {https://docs.kaleidr.com/platform-api/quota-and-rate-limits}
}

@misc{mapbox_token_management_2026,
  title  = {Token Management},
  author = {{Mapbox}},
  note   = {Accessed 17 August 2026},
  url    = {https://docs.mapbox.com/accounts/guides/tokens/}
}

@misc{mapbox_secure_2026,
  title  = {How to Use Mapbox Securely},
  author = {{Mapbox}},
  note   = {Accessed 17 August 2026},
  url    = {https://docs.mapbox.com/help/dive-deeper/how-to-use-mapbox-securely/}
}

@misc{google_maps_security_2026,
  title  = {Google Maps Platform Security Guidance},
  author = {{Google}},
  note   = {Accessed 17 August 2026},
  url    = {https://developers.google.com/maps/api-security-best-practices}
}