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

# Chaves de API

> Gere e gerencie chaves de API com prefixo swb_ para acesso programático à API REST pública do Switchbord.

Chaves de API são a forma como sistemas e scripts externos se autenticam na API REST pública do Switchbord sem uma sessão de login interativa. As chaves têm o escopo do workspace — uma chave só pode ver e operar no workspace em que foi criada — e são exibidas por completo exatamente uma vez, no momento da criação.

## Onde gerenciar as chaves

Vá para **Settings → Integrations → API Keys**. Criar, revogar e excluir chaves exige o papel `owner` ou `admin` no workspace; qualquer membro do workspace pode visualizar a lista de chaves existentes (apenas pelo nome e prefixo — nunca o segredo completo).

## Criando uma chave

1. Clique em **Create key**.
2. Dê um nome descritivo a ela (ex.: "Integração de produção", "Sincronização Zapier").
3. Escolha um escopo (veja abaixo).
4. Opcionalmente, defina uma validade — **Never**, 30 dias, 90 dias ou 1 ano.
5. Clique em **Create key**. A chave completa é exibida uma vez em uma janela — copie-a imediatamente. O Switchbord armazena apenas um hash SHA-256 e um prefixo de 8 caracteres para exibição; o segredo bruto não pode ser recuperado depois disso.

<Warning>
  Se você perder uma chave, não há como recuperá-la novamente — revogue-a e crie uma nova. Nunca cole uma chave ativa em código do lado do cliente, em um arquivo versionado ou em uma mensagem de chat.
</Warning>

## Formato da chave

As chaves geradas têm o prefixo `swb_` (algumas ferramentas legadas de provisionamento e scripts internos ainda geram chaves com prefixo `sk_live_` para fins de bootstrap — ambos os formatos são validados da mesma forma). O prefixo torna as chaves fáceis de identificar em logs e diffs, e permite que ferramentas automatizadas de varredura de segredos detectem rapidamente uma chave commitada por acidente.

## Escopos

Toda chave é criada com exatamente um escopo, que delimita o que ela pode fazer independentemente de qual endpoint ela chama:

| Escopo       | Concede                                                                                     |
| ------------ | ------------------------------------------------------------------------------------------- |
| `data_read`  | Ler contatos, conversas e templates.                                                        |
| `data_write` | Criar e atualizar registros — enviar mensagens, agendar campanhas, gravar dados de contato. |
| `management` | Acesso total a chaves de API e configurações, além das operações de dados.                  |
| `webhook`    | Enviar eventos disparados por webhook.                                                      |

Escolha o escopo mais restrito que atenda à necessidade — um script que só precisa ler contatos não deve ter uma chave `management`.

## Autenticando requisições

Passe a chave como um Bearer token:

```http theme={null}
Authorization: Bearer swb_...
```

O Switchbord resolve o workspace da chamada diretamente a partir da chave — nunca envie um ID de workspace no corpo da requisição esperando que ele seja confiável. Em cada requisição, o hash da chave é consultado, verificado em relação ao seu escopo e expiração, e `last_used_at` é atualizado.

## Revogando e excluindo

* **Revoke** invalida imediatamente uma chave para autenticação, mantendo seu registro (e histórico de uso) visível na lista, marcado como revogado.
* **Delete** remove o registro da chave por completo.

Toda ação de criação, revogação e exclusão é registrada no log de auditoria do workspace, então você sempre pode responder "quem emitiu esta chave e quando".

## Expiração

As chaves podem ser configuradas para nunca expirar, ou para expirar automaticamente após 30 dias, 90 dias ou 1 ano. Uma chave expirada falha na autenticação da mesma forma que uma revogada — as requisições retornam 403 em vez de ter sucesso silenciosamente.

## Veja também

* [Referência da API — Introdução](/pt-BR/api-reference/introduction) — a superfície da API REST pública, a URL base e os principais endpoints v1.
* [Endpoints da API de templates](/pt-BR/api-reference/template-endpoints) — um exemplo de rota autenticada e verificada por escopo.
* [Segurança — Segredos e Criptografia](/pt-BR/security/secrets-and-encryption) — como as chaves e outros segredos são hasheados e armazenados em repouso.