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

# API Keys

> Crie e gerencie API keys pelo Dashboard do SalesOS.

# Gerenciamento de API Keys

<Tip>
  Com sua chave em mãos, teste requisições assinadas no navegador no [Sandbox da API](https://play2sellsa.github.io/api-sandbox/) — cole a API key e o secret, e o playground assina as requisições automaticamente.
</Tip>

API keys permitem que suas integrações se autentiquem no SalesOS usando o esquema de requisições assinadas [P2S-SIGN-V1](/pt/api/authentication). As chaves são criadas e gerenciadas exclusivamente pelo Dashboard do SalesOS.

<Info>
  O gerenciamento de API keys requer a capability **admin.integrations**. Owners e admins do tenant possuem isso por padrão.
</Info>

***

## Criar uma chave

<Steps>
  <Step title="Abra o Dashboard">
    Acesse [dashboard.play2sell.com](https://dashboard.play2sell.com) (ou [staging](https://dashboard-staging.play2sell.com)) e faça login com sua conta de administrador.
  </Step>

  <Step title="Navegue até API Keys">
    Vá em **Integrações > API Keys** no menu lateral.
  </Step>

  <Step title="Crie uma nova chave">
    Clique em **Criar API Key** e preencha:

    * **Nome** — Um nome descritivo (ex.: "Sincronização CRM Noturna", "Formulários do Site")
    * **Escopo** — Selecione `default:sync` para integrações padrão
    * **Rate limit** — Requisições por hora (padrão: 1.000)
    * **Expiração** — Data de expiração opcional
  </Step>

  <Step title="Copie os dois valores">
    Após a criação, o Dashboard exibe **dois valores, apenas uma vez**:

    * **API Key** — identificador público, ex. `sk_live_a1b2c3d4...`. Enviado no header `Authorization` em toda requisição assinada.
    * **API Key Secret** — usado para calcular a assinatura da requisição. Nunca trafega pela rede.

    Copie os dois imediatamente e guarde em local seguro (variáveis de ambiente, gerenciador de segredos).
  </Step>
</Steps>

<Warning>
  O **API Key Secret** é exibido **apenas uma vez** na criação. Se você perder, revogue a chave e crie uma nova — não há como recuperar o secret.
</Warning>

***

## Gerenciar chaves existentes

A mesma tela **Integrações > API Keys** permite:

* **Visualizar** todas as chaves ativas, revogadas e expiradas (o secret nunca é exibido novamente)
* **Revogar** uma chave — para de funcionar imediatamente, preservando o histórico de auditoria
* **Excluir** uma chave — remove permanentemente (prefira revogar)
* **Monitorar uso** — veja contagem de requisições e data do último uso

***

## Escopos disponíveis

| Escopo         | Concede acesso a                                   |
| -------------- | -------------------------------------------------- |
| `default:sync` | Endpoints `sync_collaborators` e `sync_activities` |
| `leads:read`   | Leitura de dados de leads                          |
| `leads:write`  | Criação e atualização de leads                     |

<Note>
  Um conjunto de `scopes` vazio significa que a chave **não tem restrição de escopo** — pode acessar qualquer endpoint que aceite autenticação por API key.
</Note>

***

## Boas práticas

<AccordionGroup>
  <Accordion title="Use chaves diferentes para cada integração">
    Crie chaves separadas para cada integração (sincronização CRM, formulários do site, API de parceiros). Assim, se uma chave for comprometida, você só precisa rotacionar aquela.
  </Accordion>

  <Accordion title="Defina datas de expiração">
    Chaves sem expiração vivem para sempre. Defina uma data de expiração para forçar rotação regular — 90 dias é um bom padrão.
  </Accordion>

  <Accordion title="Use escopos mínimos">
    Se uma chave só precisa sincronizar atividades, dê apenas `default:sync`. Não deixe escopos vazios a menos que a chave realmente precise de acesso total.
  </Accordion>

  <Accordion title="Monitore o uso">
    Verifique a contagem de requisições e a data do último uso na tela de listagem do Dashboard. Chaves não usadas há meses podem ser candidatas a revogação.
  </Accordion>

  <Accordion title="Rotacione chaves sem downtime">
    1. Crie uma nova chave no Dashboard
    2. Atualize sua integração para usar a nova chave + secret
    3. Verifique que a nova chave funciona
    4. Revogue a chave antiga
  </Accordion>
</AccordionGroup>

***

## Próximos passos

<CardGroup cols={2}>
  <Card title="Autenticação" icon="shield" href="/pt/api/authentication">
    Conheça o esquema de assinatura P2S-SIGN-V1 com exemplos de código
  </Card>

  <Card title="Integração Activities" icon="plug" href="/pt/api/integrations/activities">
    Comece a enviar atividades com sua nova chave
  </Card>
</CardGroup>