Saiba como usar e gerenciar chaves de API para o Firebase
Uma chave de API é uma string exclusiva usada para encaminhar solicitações a seu projeto
do Firebase quando você interage com os serviços do Firebase e do Google. Nesta página,
você encontra as informações básicas sobre as chaves de API, além das práticas recomendadas para usar e
gerenciar essas chaves com os apps do Firebase.
Informações gerais sobre chaves de API e o Firebase
Chaves de API para Firebase são diferentes das chaves de API tradicionais
Diferentemente da forma como as chaves de API costumam ser usadas, as chaves de API para serviços do Firebase
não são usadas para controlar o acesso aos recursos de back-end. Isso só pode ser feito
com Firebase Security Rules (para controlar quais usuários finais podem acessar recursos) e
Firebase App Check (para controlar quais apps podem acessar recursos).
Normalmente, é necessário proteger rapidamente as chaves de API, por exemplo,
usando um serviço do Vault ou definindo as chaves como variáveis de ambiente. No entanto,
é possível incluir chaves de API para serviços do Firebase em arquivos de configuração ou códigos de configuração de check-in.
Apps para Apple do Firebase: encontre a chave de API com correspondência automática no arquivo de configuração
do Firebase, GoogleService-Info.plist, no
campo API_KEY.
Apps Android do Firebase: encontre a chave de API com correspondência automática no
arquivo de configuração do Firebase, google-services.json, no
campo current_key.
Apps da Web do Firebase: encontre a chave de API com correspondência automática no objeto de configuração
do Firebase, no campo apiKey.
Como usar uma chave de API
As chaves de API são usadas para identificar seu projeto do Firebase durante a interação com
os serviços do Firebase/Google. Elas são usadas especificamente para associar solicitações de API
ao projeto para cota e faturamento. Elas também são úteis para acessar
dados públicos.
Por exemplo, é possível usar explicitamente uma chave de API transmitindo o valor dela para uma chamada da API
REST como um parâmetro de consulta. Este exemplo mostra como fazer uma solicitação
para a
API com encurtador de links Dynamic Links:
POST https://firebasedynamiclinks.googleapis.com/v1/shortLinks?key=API_KEY
Quando o app faz uma chamada para uma API do Firebase que exige uma chave de API fornecida
pelo cliente para dispositivos móveis/Web, ele procura automaticamente a chave de API do projeto no
arquivo/objeto de configuração do Firebase. No entanto, é possível
fornecer chaves de API para o app usando um mecanismo diferente, incluindo variáveis de
ambiente.
Analisar e aplicar as restrições adequadas às chaves de API (recomendado)
Não é necessário tratar uma chave de API para serviços do Firebase como um
secret, mas é importante analisar e aplicar as restrições e os limites, conforme descrito nesta
seção.
Analisar as APIs adicionadas automaticamente à lista de permissões das chaves de API do Firebase
Quando o Firebase cria uma chave de API no seu projeto, adicionamos automaticamente
"Restrições de API"
a essa chave. As APIs adicionadas a essa lista de permissões são relacionadas ao Firebase e
exigem que o cliente forneça uma chave de API com a chamada. A maioria das
APIs necessárias para o uso dos serviços do Firebase não precisa estar na
lista de permissões das chaves de API.
Como o Firebase adiciona as APIs necessárias para todos os serviços do Firebase, a
lista de permissões de uma chave de API pode incluir APIs de produtos que você não usa.
É possível remover APIs da lista de permissões, mas é preciso ter muito cuidado para não
remover as APIs necessárias para o Firebase e os serviços do Firebase que você usa.
Consulte a
lista de APIs relacionadas ao Firebase
que precisam estar na lista de permissões de cada serviço/produto. Caso contrário,
você vai receber erros ao fazer chamadas para os serviços do Firebase.
Reduzir cota em caso de uso de Authentication com base em senha
Se você usar o Firebase Authentication com senha e alguém conseguir sua chave de API, essa pessoa
não vai ter acesso aos dados do banco de dados ou do Cloud Storage do projeto do Firebase
desde que essas informações estejam protegidas pelas
regras de segurança do Firebase Security Rules. No entanto, ela poderá usar a chave de API para acessar
os endpoints de autenticação do Firebase e fazer solicitações de autenticação
para o projeto.
Para reduzir a possibilidade de alguém usar uma chave de API de forma indevida para
tentar um ataque de força bruta, é possível reduzir a cota padrão dos
endpoints identitytoolkit.googleapis.com para refletir as expectativas normais
de tráfego do seu app. Lembre-se de que, se você reduzir essa cota, e seu app
ganhar muitos usuários, erros de login poderão acontecer até você aumentar a cota.
É possível alterar as cotas da API do seu projeto no Console do Google Cloud.
Usar chaves de API separadas e restritas para qualquer serviço que não seja do Firebase
As chaves de API utilizadas para serviços do Firebase geralmente não precisam ser tratadas
como secrets. Mesmo assim, tome algumas precauções extras com as chaves de API usadas
com outras APIs Google Cloud.
Se você usa uma API Google Cloud (em qualquer plataforma) que não é para um serviço/produto do Firebase, recomendamos criar chaves de API restritas e separadas para usar com essas APIs. Isso é importante se a API for de um serviço faturável do Google Cloud.
Por exemplo, se você usa Firebase ML e as APIs Cloud Vision no iOS,
crie chaves de API separadas que serão usadas apenas
para acessar essas APIs.
Ao usar chaves de API separadas e restritas para APIs que não são do Firebase, é possível girar ou
substituir as chaves quando necessário e adicionar outras restrições às chaves
de API, sem interromper o uso dos serviços do Firebase.
Conferir instruções para criar chaves específicas da API
Com estas instruções, você aprenderá a criar uma chave de API restrita e separada para uma
API falsa chamada Super Service API.
Etapa 1: configure suas chaves de API atuais para proibir o acesso a Super Service API
Abra a página Credenciais do console do Google Cloud. Quando solicitado, selecione o projeto.
Para cada chave de API na lista, abra a visualização de edição.
Na seção Restrições da API, selecione Restringir chave e adicione à
lista de todas as APIs que você quer que a chave tenha acesso. Não
inclua a API para a qual você está criando a chave separada
(exemplo: Super Service API).
Quando você configura as restrições de API de uma chave de API, declara explicitamente
as APIs a que a chave tem acesso. Por padrão, quando a seção
Restrições da API tiver a opção Não restringir a chave selecionada, uma chave de API
poderá ser usada para acessar qualquer API ativada para o projeto.
Agora, suas chaves de API existentes não concederão acesso a Super Service API, mas
continuarão funcionando para as APIs adicionadas à
lista de restrições da API.
Etapa 2: crie e use uma nova chave de API para acessar o Super Service API
Volte para a página
Credenciais. Verifique se seu projeto do Firebase ainda está selecionado.
Clique em Criar credenciais > Chave de API. Anote a nova chave de API e clique em
Restringir chave.
Na seção Restrições da API, selecione Restringir chave e adicione à
lista somente a Super Service API.
Essa nova chave de API concede acesso somente à Super Service API.
Configure o app e os serviços para usar a nova chave de API.
Usar chaves de API específicas do ambiente (recomendado)
Se você configurar diferentes projetos do Firebase para diferentes ambientes, como
preparação e produção, é importante que cada instância do app interaja com o
projeto do Firebase correspondente. Por exemplo, sua instância de app de teste nunca
deve se comunicar com o projeto de produção do Firebase. Isso também significa que seu app de teste precisa usar chaves de API associadas ao projeto de teste do Firebase.
Para minimizar os problemas ao fazer alterações no código desde o desenvolvimento até o preparo e a produção, em vez de incluir chaves de API no próprio código, defina-as como variáveis de ambiente ou adicione-as a um arquivo de configuração.
Se você estiver usando o Firebase Local Emulator Suite para desenvolvimento com
o Firebase ML, será preciso criar e usar uma chave de API somente para depuração. As instruções
para criar esse tipo de chave estão na
documentação do Firebase ML.
Perguntas frequentes e solução de problemas
Perguntas frequentes
As chaves de API para serviços do Firebase são restritas por padrão?
Sim, por padrão, todas as chaves de API provisionadas automaticamente pelo Firebase para uso com
APIs relacionadas ao Firebase têm
Restrições de API
aplicadas automaticamente. Consulte a
lista de APIs relacionadas ao Firebase
que estão nesta lista de permissões.
As APIs adicionadas a essa lista são aquelas chamadas pelos serviços do Firebase do
código do cliente e exigem chaves de API para a identificação do seu projeto ou
app do Firebase. A maioria das APIs necessárias para usar os serviços do Firebase não
precisa estar na lista de permissões das chaves de API.
Como o Firebase adiciona as APIs necessárias para todos os serviços do Firebase, a
lista de permissões de uma chave de API pode incluir APIs de produtos que você não usa. É possível remover APIs da lista de permissões, mas é preciso ter muito cuidado para não
remover as APIs necessárias para o Firebase e os serviços do Firebase que você usa.
Consulte a lista de APIs relacionadas ao Firebase
que precisam estar na lista de permissões de cada serviço/produto. Caso contrário,
você vai receber erros ao fazer chamadas para os serviços do Firebase.
É possível conferir todas as chaves de API e as "restrições de API" no painel
APIs e serviços > Credenciais
no console Google Cloud.
Observe como o Firebase aplica essas "restrições de API":
A partir de maio de 2024, todas as chaves de API novas provisionadas automaticamente pelo Firebase serão
restringidas automaticamente à
lista de APIs relacionadas ao Firebase.
Em maio de 2024, todas as chaves de API não restritas e atuais que o Firebase provisionou
automaticamente estarão restritas à
lista de APIs relacionadas ao Firebasee a qualquer uma das APIs ativadas atualmente do projeto.
As chaves de API já restritas que o Firebase provisionou automaticamente não foram alteradas.
As chaves de API que não foram provisionadas automaticamente pelo Firebase não foram
alteradas.
Como posso determinar qual chave de API
está associada ao meu app do Firebase?
Você pode usar qualquer uma das opções a seguir para determinar qual chave de API está
associada ao seu app do Firebase:
Esse keyString é o mesmo valor que pode ser encontrado no artefato de configuração
do app
(Apple |
Android |
Web).
Posso
ter duas chaves de API listadas para o mesmo app do Firebase no meu objeto/arquivo
de configuração?
Apps para Apple do Firebase: cada app tem o próprio arquivo de configuração e pode ter apenas uma chave de API listada.
Apps Android do Firebase: todos os apps para Android no projeto do Firebase são listados no mesmo arquivo de configuração, e cada app pode ter apenas uma chave de API listada. No entanto, cada app nesse arquivo de configuração pode ter uma chave diferente listada.
Apps da Web do Firebase: cada app tem o próprio objeto de configuração e pode ter apenas uma chave de API listada.
No entanto, é possível usar várias chaves de API com um app. É necessário fornecer um mecanismo para que o app acesse essas outras chaves de API, como, por exemplo, usando uma variável de ambiente. O mecanismo de acesso a outras chaves de API não pode depender das
que estão listadas no arquivo/objeto de configuração do Firebase.
Como o Firebase
sabe qual chave de API corresponde a um app (como no objeto/arquivo
de configuração)?
Se o Firebase não encontrar chaves restritas correspondentes, ele vai listar no
objeto/arquivo de configuração iOS key para apps da Apple, Android key para
apps Android e Browser key para apps da Web (presumindo que essas chaves existam
e não tenham "Restrições de aplicativo" que impeçam a correspondência com o
app).
Posso excluir manualmente
a chave e o campo da API do meu arquivo/objeto de configuração do Firebase?
Sim, é possível excluir manualmente sua chave de API do arquivo/objeto de configuração. No entanto, é preciso fornecer outro mecanismo para que o aplicativo acesse uma chave de API, por exemplo, por meio de uma variável de ambiente. Caso contrário, as chamadas para os serviços do Firebase falharão.
Posso editar manualmente meu arquivo/objeto de configuração do Firebase com chaves de API diferentes?
Sim, é possível editar manualmente um arquivo/objeto de configuração para associar uma outra chave de API a um app.
Posso mover uma
chave de API de um projeto do Firebase para outro?
Não, uma chave de API identifica apenas um projeto específico e não pode ser movida para outro.
O que acontece se eu excluir uma chave de API listada no Console do Google Cloud?
Se você excluir uma chave de API que está sendo usada por um app, as chamadas de API
dele falharão. Talvez você receba relatórios, e-mails ou erros ao tentar usar uma chave de API inválida.
A exclusão de uma chave de API é permanente e não pode ser desfeita.
Quais APIs são necessárias na lista de permissões "Restrições de API" para uma chave de API do Firebase?
Para uma chave de API do Firebase, as únicas APIs que precisam estar na lista de permissões de "Restrições de API" da chave são as que exigem que o cliente forneça uma chave de API com a chamada. Apenas poucas APIs relacionadas ao Firebase têm esse
requisito. A maioria das APIs relacionadas ao Firebase ativadas no seu projeto não precisa estar
na lista de permissões "Restrições de API" da chave.
Use a tabela a seguir para determinar quais APIs relacionadas ao Firebase precisam ser
incluídas na lista de permissões "Restrições de API" de uma chave de API do Firebase. As chaves de API do Firebase só podem ser usadas para serviços do Firebase. Saiba mais sobre
como criar
chaves de API separadas e restritas para tipos específicos de APIs.
É possível ver e gerenciar as chaves de API do seu projeto no painel APIs e serviços > Credenciais no Console do Google Cloud.
* Obrigatório apenas se você estiver usando a chave da API do Firebase com ferramentas
de terceiros ou acesso REST direto ao serviço/produto do Firebase.
** Necessário para versões anteriores do SDK do produto. Se você estiver usando
a versão mais recente do SDK, a API não precisará estar na lista de permissões
da chave.
Solução de problemas
Como corrigir um erro API_KEY_SERVICE_BLOCKED ou 403 Forbidden que informa que as solicitações para essa API estão bloqueadas?
Siga as orientações nestas perguntas frequentes se você receber um erro API_KEY_SERVICE_BLOCKED
ou um erro semelhante a este:
Forbidden: 403 POST https://example-service.googleapis.com/method: Requests to this API example-service.googleapis.com method google.example-service.rest.method are blocked.
A chave de API usada pelo app para chamar a API provavelmente tem
Restrições de API
aplicadas a ela, e a lista de permissões da chave não inclui essa API.
Se você receber esse erro ao tentar usar um serviço que não é do Firebase, recomendamos criar uma nova chave de API especificamente para esse serviço e API. As chaves de API do Firebase só podem ser usadas para serviços/produtos do Firebase.
Saiba mais sobre
como criar chaves de API separadas e restritas para tipos específicos de APIs.
Como posso corrigir
este erro? "Falha ao buscar o ID de métricas do app do Firebase no
servidor."
A chave de API usada pelo app da Web provavelmente tem
Restrições de API
aplicadas a ela. Nesse caso, verifique se a API Firebase Management
está na lista de APIs permitidas.
Recebi um e-mail ou erro informando que
minha chave de API é inválida. O que aconteceu e como posso corrigir isso?
Veja a seguir algumas das causas mais comuns de chaves de API inválidas:
A chave de API tem
Restrições
aplicadas a ela. Isso a torna incompatível com o app que tenta usar a chave
(Restrições de aplicativo) ou inutilizável para a API chamada (Restrições
de API).
A chave de API foi excluída do projeto no Console do Google Cloud.
A chave de API não foi criada para o ID do projeto listado no objeto/arquivo
de configuração do Firebase para o app.