- O App ID e o Organization ID são identificadores públicos, seguros para uso em código do lado do cliente e inicialização do SDK.
- A Chave de API do App e a Chave de API da Organização são segredos privados. Armazene-as com segurança e nunca as exponha em código do lado do cliente.
App ID
O App ID é um UUID (v4) público que identifica seu aplicativo OneSignal. Você o utiliza para:- Inicializar o SDK (Configuração do SDK Mobile, Configuração do SDK Web)
- Fazer requisições de API como Criar mensagem e Criar usuário
Seu App ID é seguro para uso na inicialização do SDK no lado do cliente. Ele não é um segredo.
Organization ID
O Organization ID (Org ID) é um UUID (v4) que agrupa todos os aplicativos sob seu plano de cobrança. Você precisa dele para APIs de nível organizacional como: Encontre-o em Organizations > Sua organização > Keys & IDs ou através da API View an app.
Chaves de API
Existem dois tipos de chaves de API. Ambas autenticam requisições da REST API e devem ser mantidas em segredo. Escolha aquela que corresponde ao que você quer fazer:| Chave | Usada para |
|---|---|
| Chave de API do App | Um aplicativo específico: enviar mensagens, criar usuários, ler estatísticas. |
| Chave de API da Organização | Em toda a sua organização: criar aplicativos e gerenciar outras chaves de API. |
Você pode criar até 16 Chaves de API do App por aplicativo e 16 Chaves de API da Organização por organização.
Chave de API do App
Use uma Chave de API do App para qualquer requisição da REST API restrita a um único aplicativo: envio de mensagens; criação ou atualização de usuários; ou leitura do histórico de mensagens. O painel nunca exibe os valores de chaves de API existentes. A string na coluna Key ID é apenas um identificador interno, não a chave. Para obter novamente um segredo funcional, siga os passos abaixo para criar uma nova chave de API ou rotacione uma chave existente. A rotação gera um novo valor mantendo o mesmo Key ID, nome e lista de permissão de IP, e o valor antigo para de funcionar imediatamente.
Acesse Settings > Keys & IDs do app
No painel OneSignal, selecione seu aplicativo e vá para Settings > Keys & IDs.
Clique em Add Key
Insira um nome descritivo (por exemplo,
Backend service). Opcionalmente, adicione uma lista de permissão de IP para que a chave funcione apenas a partir de servidores aprovados.
Chave de API da Organização
Use uma Chave de API da Organização para operações que abrangem todos os aplicativos da sua organização. Endpoints comuns:- Gerenciamento de aplicativos: Criar um aplicativo, Visualizar aplicativos
- Gerenciamento de chaves de API: Criar chave de API, Deletar chave de API, Rotacionar chave de API
Acesse Keys & IDs da organização
No painel OneSignal, vá para Organizations > Sua organização > Keys & IDs.
Clique em Add Key e dê um nome
Insira um nome descritivo (por exemplo,
App provisioning). Opcionalmente, adicione uma lista de permissão de IP.
Lista de permissão de IP
A lista de permissão de IP é opcional, mas fortemente recomendada. Ela restringe o uso da chave de API a endereços IP específicos, de modo que uma chave vazada não possa ser usada de outro lugar.- Insira blocos CIDR separados por espaço (exemplo:
192.0.2.0/24 192.0.2.123/32). - Requisições de IPs não permitidos são negadas.
- Serviços de backend com IPs estáticos.
- Ambientes de produção de alta segurança.
Gerenciar chaves de API
Depois de criar uma chave, você pode editá-la, rotacioná-la ou deletá-la na lista de chaves em Settings > Keys & IDs. Chaves de API do App também suportam essas operações via REST API. Chaves de API da Organização são exclusivas do painel.Editar uma chave
Atualize o nome ou a lista de permissão de IP sem alterar o valor secreto. Nenhuma alteração na integração é necessária. Use o painel, ou a API Update API key (apenas Chaves de API do App).Rotacionar uma chave
A rotação gera um novo segredo mantendo o mesmo Key ID, nome e lista de permissão de IP. O segredo antigo para de funcionar imediatamente. Rotacione uma chave quando:- A chave foi exposta.
- Um membro da equipe com acesso saiu.
- Uma rotação de segurança de rotina está agendada.
- Você perdeu o valor original da chave e precisa de um segredo funcional.
Deletar uma chave
A exclusão remove a chave permanentemente e bloqueia imediatamente o acesso à API que a utilizava. Use a exclusão quando uma chave não for mais necessária. Use o painel, ou a API Delete API key (apenas Chaves de API do App).Migrando de chaves de API legadas
O OneSignal introduziu as Chaves de API do App e da Organização (com nomes, rotação e lista de permissão de IP) em novembro de 2024. A chave User Auth legada e a chave REST API original ainda são aceitas, mas a interface de gerenciamento delas foi removida e novas chaves não podem ser criadas.Criar uma nova chave
Crie uma nova Chave de API do App ou Chave de API da Organização dependendo de qual chave legada você está substituindo.
Atualizar seu código
Substitua a chave legada pelo novo valor em todos os serviços que se autenticam contra o OneSignal.
Atualizar a URL base da API
Altere a URL base da sua API de
https://onesignal.com/api/v1/ para https://api.onesignal.com.Verifique as requisições de API em staging antes de desativar sua chave legada em produção.
Bloquear acesso à API
Para revogar uma chave imediatamente, rotacione ou delete em Settings > Keys & IDs. Requisições que usam o valor antigo falham imediatamente. Para parar o envio de mensagens ou pausar um aplicativo completamente, consulte Aplicativos e organizações desativados.Melhores práticas de segurança
- Armazene as chaves de API em um backend seguro (nunca no lado do cliente).
- Use variáveis de ambiente ou um gerenciador de segredos.
- Habilite a lista de permissão de IP quando possível.
- Rotacione as chaves periodicamente.
- Use chaves separadas para staging e produção.
Perguntas frequentes
Como encontro minha chave de API?
Os valores das chaves de API começam comos_v2_app_ e são exibidos apenas uma vez, imediatamente após a criação ou rotação da chave. A coluna Key ID no painel é um identificador interno, não a chave de API, e retorna 401 Unauthorized se usada para autenticação. Se você não salvou o valor da sua chave, rotacione a chave para gerar um novo. Consulte Chave de API do App ou Chave de API da Organização para ver o fluxo completo.
Posso recuperar uma Chave de API do App legada?
Não. O OneSignal não exibe mais Chaves de API do App legadas. Se você não conseguir encontrar o valor no seu código, gere uma nova Chave de API do App e atualize suas integrações.Qual é a diferença entre um App ID, Chave de API do App e Chave de API da Organização?
- App ID: Um identificador público para seu app. Usado na configuração do SDK e em requisições de API para especificar o app.
- Chave de API do App: Um segredo usado para enviar mensagens e gerenciar usuários de um app.
- Chave de API da Organização: Um segredo usado para gerenciar apps e configurações no nível da organização em toda a sua conta.
O que acontece se minha chave de API for exposta?
Rotacione a chave imediatamente. A rotação invalida o valor antigo e emite um novo mantendo o mesmo Key ID, nome e lista de permissão de IP. Em seguida, atualize todos os serviços que usam a chave. Revise seus logs de auditoria em busca de atividade inesperada na API.Páginas relacionadas
Visão geral da REST API
Autentique requisições e entenda a REST API do OneSignal.
Limites de taxa
Limites de taxa por chave e melhores práticas para integrações de alto volume.
Logs de auditoria
Revise a atividade da API e do painel por chave, usuário e tempo.
Aplicativos e organizações desativados
Pause ou encerre um aplicativo e entenda as implicações de cobrança.