<!-- https://www.akrus.digital/docs/autenticacao · revisado em 2026-10-08 · gerado do mesmo conteúdo da página HTML -->
_Comece por aqui · v1 em prévia_

# Uma credencial, um produtor, escopos explícitos.

Envie a credencial no cabeçalho Authorization em cada consulta.

> **Antes de integrar**
>
> Contrato em prévia. A implementação foi validada localmente; a liberação em produção ainda precisa ser confirmada pela equipe. O acesso programático exige plano Scale efetivo, credencial e escopos autorizados. Solicite acesso e a URL do ambiente antes de integrar.
>
> [Ver disponibilidade](https://www.akrus.digital/docs/ambientes)

## Bearer token

A credencial é emitida pela administração e apresentada em claro uma única vez. O produtor é determinado pela credencial; parâmetros de consulta não selecionam outra conta.

```
Authorization: Bearer <sua-credencial>
```

## Escopos

Cada recurso exige a sua permissão. Peça só os escopos que a integração usa.

| Permissão | Recurso |
| --- | --- |
| products:read | GET /api/v1/products |
| sales:read | GET /api/v1/sales |
| access:read | GET /api/v1/access |

## Armazenamento e revogação

Guarde o segredo fora do repositório, do navegador e dos logs. Em caso de exposição, solicite a revogação e a emissão de uma nova credencial. Uma credencial revogada passa a retornar 401.

## Troca planejada de credencial

1. **Solicite a nova chave** — Informe os escopos necessários. Guarde o segredo na apresentação inicial, fora do código-fonte.
2. **Atualize a integração** — Substitua o segredo no ambiente autorizado e valide uma leitura com os recursos utilizados.
3. **Revogue a anterior** — Solicite a revogação e confirme que nenhum processo depende da chave antiga. Em caso de exposição, priorize a revogação imediata.

> **Falhas de autenticação**
>
> Credencial ausente, inválida ou revogada retorna unauthenticated. Uma credencial válida sem o escopo necessário ou sem plano Scale efetivo retorna forbidden_scope. O plano é conferido a cada chamada; uma chave antiga não preserva o acesso após um downgrade. Não use mensagens de erro como lógica de integração; use os códigos.
>
> [Ver todos os códigos de erro](https://www.akrus.digital/docs/erros)

## Dúvidas frequentes

### Posso usar a mesma credencial para vários produtores?

Uma credencial está vinculada a um produtor. O contrato não permite escolher outra conta por query string.

### Uma chave revogada volta a funcionar?

A revogação não é um mecanismo de pausa. Solicite uma nova credencial se precisar restabelecer o acesso.

---

Anterior: [Início rápido](https://www.akrus.digital/docs/inicio-rapido) · Próximo: [Ambientes e disponibilidade](https://www.akrus.digital/docs/ambientes)
