Chaves de API
Chaves de API permitem que sistemas externos acessem a plataforma programaticamente, sem usar o dashboard.
Criando uma chave
- No painel, vá em Chaves de API
- Clique em Nova chave
- Preencha um nome descritivo (ex: "Sistema ERP", "App portaria")
- Selecione as permissões necessárias
- Opcionalmente, defina uma data de expiração
- Clique em Criar chave
Atenção
A chave completa é exibida apenas uma vez após a criação. Copie e guarde em local seguro. Se perdê-la, será necessário criar uma nova.
Permissões (scopes)
Cada chave tem permissões granulares organizadas por recurso:
| Recurso | Leitura | Escrita |
|---|---|---|
| Reconhecimentos | recognitions:read — Listar e buscar | recognitions:write — Criar via API |
| Câmeras | cameras:read — Listar câmeras | cameras:write — Criar, editar, excluir |
| Alertas | alerts:read — Listar alertas | alerts:write — Gerenciar alertas |
| Webhooks | webhooks:read — Listar webhooks | webhooks:write — Gerenciar webhooks |
Ao criar a chave, você pode selecionar permissões individualmente ou por grupo (o checkbox do grupo seleciona/desmarca todos).
Dica
Siga o princípio do menor privilégio: dê a cada chave apenas as permissões que a integração realmente precisa.
Usando a chave
Envie a chave no header Authorization de cada requisição:
GET /api/recognitions
Authorization: Bearer pk_a1b2c3d4e5f6...
Expiração
Chaves podem ter uma data de expiração opcional. Após essa data, requisições retornarão HTTP 401. Chaves sem data de expiração funcionam indefinidamente.
Editando uma chave
Você pode alterar o nome, permissões, status (ativa/inativa) e expiração de uma chave existente a qualquer momento. Clique no menu de ações (⋮) e selecione Editar.
Revogando uma chave
Para revogar uma chave permanentemente, clique no menu de ações (⋮) e selecione Revogar. A chave será excluída e qualquer integração que a utilize deixará de funcionar imediatamente.
Identificação
Na tabela de chaves, cada chave exibe um prefixo (ex: pk_a1b2c3d4••••••••) para que você possa identificá-la sem expor o valor completo.
Erros de autenticação
| Código | Significado |
|---|---|
| 401 | Chave ausente, inválida, expirada ou inativa |
| 403 | Chave válida, mas sem permissão para este recurso |