Autenticação

Coloque a chave no cabeçalho Authorization, depois da palavra Bearer e de um espaço:

Authorization: Bearer gm_…

Só procuramos a chave nesse cabeçalho. Não existe cabeçalho X-API-Key, e nunca lemos a chave da URL, porque URLs acabam parando em logs.

Para testar uma chave, consulte seu uso. É de graça e não muda nada. O SDK manda o cabeçalho por você depois que recebe a chave:

curl https://api.gmaps.dev/v1/usage \
  -H "Authorization: Bearer $GMAPS_API_KEY"

Crie chaves no console, em Chaves de API. Dê a cada uma um nome que diga onde ela vai ser usada, como “servidor de produção” ou “Claude no meu notebook”, para saber qual revogar depois.

A chave só aparece uma vez, quando você a cria. Não guardamos a chave em si, então não dá para mostrá-la de novo: se perder, crie outra. O console mostra o começo de cada chave e quando ela foi usada pela última vez, para você saber qual é qual.

Quantas chaves você pode ter ao mesmo tempo depende do plano. Chaves revogadas não contam:

Chegou ao limite? Revogue uma chave que você não usa mais ou mude para um plano maior.

Mais chaves não dão mais requisições. O limite por minuto vale para a conta toda, não para cada chave. Os números estão em Limites.

Uma chave funciona até você revogá-la. Revogue no console quando parar de usar ou se ela puder ter vazado. Ela para de funcionar na hora, e não dá para desfazer. O que ela gastou continua na página Uso.

Para trocar uma chave sem deixar nada parado, crie a nova primeiro, passe seu código para ela e só então revogue a antiga.

Uma chave gasta seus créditos, então trate a chave como uma senha:

• Deixe a chave fora do código e fora do git. Leia de uma variável de ambiente, como fazem os exemplos daqui.
• Deixe a chave fora de páginas web e de apps que você distribui, onde qualquer pessoa consegue ler. Chame a API do seu servidor. Páginas de outros sites nem conseguem chamar a API: ela só aceita chamadas de navegador vindas do gmaps.dev.
• Use uma chave para cada lugar onde seu código roda. Assim dá para revogar uma sem parar as outras.

Uma chamada recusada não muda nada e não custa nada. A resposta diz o que deu errado:

Uma chave errada e uma revogada recebem a mesma resposta.

Todo erro tem o mesmo formato. Esta é a resposta de uma chamada sem chave, e Erros lista todos os códigos:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Send your API key as \"Authorization: Bearer gm_…\". Create one at https://console.gmaps.dev/keys, then retry.",
    "messageKey": "serverErrors.unauthorized"
  }
}

Um agente de IA conectado por MCP manda o mesmo cabeçalho, com a mesma chave. As chamadas dele contam nos mesmos limites e gastam os mesmos créditos que as do seu código. Listar as ferramentas não precisa de chave, então o agente vê o que pode fazer antes de ter uma.

Quando você cria uma chave, o console mostra as configurações de MCP do seu agente com a chave já dentro, prontas para colar.

Estas respondem sem chave:

• GET /v1/attributions: os projetos de código aberto que usamos e as licenças deles.
• GET /v1/exports/{id}/download: o arquivo de uma exportação. O token no link é o que abre o arquivo, então só compartilhe o link com quem deve ter o arquivo. Ele funciona por 24 horas. Veja mais em Exportações.
• GET /openapi.json: a API inteira, descrita para ferramentas que geram clientes.
• GET /health: se a API está no ar.

Toda resposta traz o cabeçalho x-request-id. Guarde esse id junto com seus logs. Se algo der errado, mande para o suporte, e conseguimos achar exatamente aquela chamada.

Você também pode mandar um x-request-id seu, com até 64 letras, números, pontos, hifens e underscores. Usamos o seu em vez de criar outro, e assim seus logs e os nossos têm o mesmo id. Se o seu não seguir essas regras, usamos um nosso.

No SDK, um erro vindo da API traz esse id em requestId.

De cada chamada, a API registra o id, o método, o caminho, o status e quanto tempo levou. O servidor web na frente dela também registra a URL completa, com a query string, o seu IP e os cabeçalhos da requisição, menos o Authorization, e guarda tudo isso por 30 dias. Nenhum dos dois registra a sua chave nem o corpo da requisição.