> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Keys & IDs

> Encontre e gerencie seu App ID, Organization ID e chaves de API do OneSignal. Aprenda a criar, rotacionar, proteger e migrar chaves com segurança.

Sua conta OneSignal inclui **IDs públicos** (App ID, Organization ID) e **chaves de API privadas** (App API key, Organization API key).

* O [App ID](#app-id) e o [Organization ID](#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](#app-api-key) e a [Chave de API da Organização](#organization-api-key) são segredos privados. Armazene-as com segurança e nunca as exponha em código do lado do cliente.

Encontre-as no painel OneSignal em **Settings > Keys & IDs** (nível de app) ou **Organizations > Sua organização > Keys & IDs** (nível de organização).

***

## 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

Encontre seu App ID no painel em **Settings > Keys & IDs** ou através da API [View apps](/reference/view-apps).

<Frame caption="Localização do App ID em Settings > Keys & IDs">
  <img src="https://mintcdn.com/onesignal/W0DIQbUDatcgdZf6/images/dashboard/dashboard-keys-and-ids-app-id-number.jpg?fit=max&auto=format&n=W0DIQbUDatcgdZf6&q=85&s=07fa6040dbc41ffa7dff116a0b1ad575" alt="Valor do App ID destacado na página de configurações Keys & IDs" width="1375" height="528" data-path="images/dashboard/dashboard-keys-and-ids-app-id-number.jpg" />
</Frame>

<Check>
  Seu App ID é seguro para uso na inicialização do SDK no lado do cliente. Ele não é um segredo.
</Check>

***

## 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:

* [Criar um aplicativo](/reference/create-an-app)
* [Atualizar um aplicativo](/reference/update-an-app)

Encontre-o em **Organizations > Sua organização > Keys & IDs** ou através da API [View an app](/reference/view-an-app).

<Frame caption="Localização do Organization ID no painel OneSignal">
  <img src="https://mintcdn.com/onesignal/MWGmj5X1CnFliD-c/images/dashboard/dashboard-keys-and-ids-organization-id.png?fit=max&auto=format&n=MWGmj5X1CnFliD-c&q=85&s=b28d6312569975a67ca3eb1be9f568e4" alt="Painel OneSignal mostrando o Organization ID em Keys & IDs" width="2560" height="1228" data-path="images/dashboard/dashboard-keys-and-ids-organization-id.png" />
</Frame>

***

## 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](#app-api-key)                  | Um aplicativo específico: enviar mensagens, criar usuários, ler estatísticas.  |
| [Chave de API da Organização](#organization-api-key) | Em toda a sua organização: criar aplicativos e gerenciar outras chaves de API. |

<Note>
  Você pode criar até 16 Chaves de API do App por aplicativo e 16 Chaves de API da Organização por organização.
</Note>

### 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](#rotate-a-key). 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.

<Frame caption="O painel mostra o Key ID, não o valor da chave de API. O valor real (começando com os_v2_app_) é exibido apenas uma vez, quando a chave é criada ou rotacionada.">
  <img src="https://mintcdn.com/onesignal/yYUi2EK-maheXJet/images/dashboard/api-key-list.png?fit=max&auto=format&n=yYUi2EK-maheXJet&q=85&s=e6c8dcfa23dc56ec4a2de364ffdffd99" alt="Tabela de chaves de API no painel OneSignal mostrando a coluna Key ID, que não é o valor da chave de API" width="2728" height="1104" data-path="images/dashboard/api-key-list.png" />
</Frame>

**Criar uma Chave de API do App**

Siga estes passos para criar uma Chave de API do App no painel ou use a API [Create API key](/reference/create-api-key).

<Steps>
  <Step title="Acesse Settings > Keys & IDs do app">
    No painel OneSignal, selecione seu aplicativo e vá para **Settings > Keys & IDs**.
  </Step>

  <Step title="Clique em Add Key">
    Insira um nome descritivo (por exemplo, `Backend service`). Opcionalmente, adicione uma [lista de permissão de IP](#ip-allowlist) para que a chave funcione apenas a partir de servidores aprovados.
  </Step>

  <Step title="Clique em Create e copie o valor da chave imediatamente">
    O valor começa com `os_v2_app_` e é exibido **apenas uma vez**. Armazene-o em um gerenciador de segredos ou variável de ambiente do backend imediatamente.

    <Frame caption="Valor da chave de API gerada, exibido apenas uma vez">
      <img src="https://mintcdn.com/onesignal/QOf62tdZP66tkOD2/images/docs/generated-api-key.png?fit=max&auto=format&n=QOf62tdZP66tkOD2&q=85&s=81c7a600d8d5f88b79c47a027acc0c41" alt="Chave de API gerada exibida após a criação" width="764" height="768" data-path="images/docs/generated-api-key.png" />
    </Frame>
  </Step>
</Steps>

<Warning>
  Trate as Chaves de API do App como senhas:

  * Nunca as exponha no código do cliente mobile ou web.
  * Nunca as envie para repositórios públicos (como GitHub).
  * Armazene-as em um backend seguro ou gerenciador de segredos.
</Warning>

### 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](/reference/create-an-app), [Visualizar aplicativos](/reference/view-apps)
* **Gerenciamento de chaves de API:** [Criar chave de API](/reference/create-api-key), [Deletar chave de API](/reference/delete-api-key), [Rotacionar chave de API](/reference/rotate-api-key)

**Criar uma Chave de API da Organização:**

Chaves de API da Organização são exclusivas do painel. Não há endpoint de API para criá-las.

<Steps>
  <Step title="Acesse Keys & IDs da organização">
    No painel OneSignal, vá para **Organizations > Sua organização > Keys & IDs**.
  </Step>

  <Step title="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](#ip-allowlist).
  </Step>

  <Step title="Clique em Create e copie o valor da chave imediatamente">
    O valor começa com `os_v2_app_` e é exibido **apenas uma vez**. Armazene-o com segurança imediatamente.
  </Step>
</Steps>

<Frame caption="Página Keys & IDs da organização onde as Chaves de API da Organização são criadas">
  <img src="https://mintcdn.com/onesignal/W0DIQbUDatcgdZf6/images/dashboard/default-org-api-keys-and-ids.jpg?fit=max&auto=format&n=W0DIQbUDatcgdZf6&q=85&s=d014d99705d175a153d43444b42adca3" alt="Seção da Chave de API da Organização no painel Keys & IDs" width="1846" height="840" data-path="images/dashboard/default-org-api-keys-and-ids.jpg" />
</Frame>

<Warning>
  As Chaves de API da Organização concedem acesso a todos os aplicativos da sua organização. Trate-as com cuidado extra e compartilhe-as apenas com serviços que realmente precisam de acesso em nível organizacional.
</Warning>

***

## 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.

Use a lista de permissão de IP para:

* Serviços de backend com IPs estáticos.
* Ambientes de produção de alta segurança.

<Frame caption="Criando uma chave de API com lista de permissão de IP habilitada">
  <img src="https://mintcdn.com/onesignal/QOf62tdZP66tkOD2/images/docs/ip-allowlist-config.png?fit=max&auto=format&n=QOf62tdZP66tkOD2&q=85&s=d2bdf5bec27c8a982c027d428687a3b9" alt="Campo de configuração da lista de permissão de IP no modal de criação de chave de API" width="764" height="542" data-path="images/docs/ip-allowlist-config.png" />
</Frame>

***

## 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](/reference/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.

<Warning>
  Após rotacionar uma chave, atualize todos os serviços que usavam o valor antigo. Requisições com a chave antiga falham imediatamente.
</Warning>

Use o painel, ou a API [Rotate API key](/reference/rotate-api-key) (apenas Chaves de API do App).

### 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](/reference/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.

<Steps>
  <Step title="Criar uma nova chave">
    Crie uma nova [Chave de API do App](#app-api-key) ou [Chave de API da Organização](#organization-api-key) dependendo de qual chave legada você está substituindo.
  </Step>

  <Step title="Atualizar seu código">
    Substitua a chave legada pelo novo valor em todos os serviços que se autenticam contra o OneSignal.
  </Step>

  <Step title="Atualizar a URL base da API">
    Altere a URL base da sua API de `https://onesignal.com/api/v1/` para `https://api.onesignal.com`.
  </Step>

  <Step title="Verificar e então desativar a chave legada">
    Teste as requisições da API em um ambiente de staging e depois desative ou delete a chave legada em **Settings > Keys & IDs**.
  </Step>
</Steps>

<Check>
  Verifique as requisições de API em staging antes de desativar sua chave legada em produção.
</Check>

***

## Bloquear acesso à API

Para revogar uma chave imediatamente, [rotacione](#rotate-a-key) ou [delete](#delete-a-key) 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](./disabled-apps).

***

## 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 com `os_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](#rotate-a-key) para gerar um novo. Consulte [Chave de API do App](#app-api-key) ou [Chave de API da Organização](#organization-api-key) 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](#rotate-a-key) 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](./audit-logs) em busca de atividade inesperada na API.

***

## Páginas relacionadas

<Columns cols={2}>
  <Card title="Visão geral da REST API" icon="code" href="/reference/rest-api-overview">
    Autentique requisições e entenda a REST API do OneSignal.
  </Card>

  <Card title="Limites de taxa" icon="clock" href="/reference/rate-limits">
    Limites de taxa por chave e melhores práticas para integrações de alto volume.
  </Card>

  <Card title="Logs de auditoria" icon="file-shield" href="./audit-logs">
    Revise a atividade da API e do painel por chave, usuário e tempo.
  </Card>

  <Card title="Aplicativos e organizações desativados" icon="ban" href="./disabled-apps">
    Pause ou encerre um aplicativo e entenda as implicações de cobrança.
  </Card>
</Columns>