Aston API

1. Autenticação

Toda requisição deve trazer o header:

X-API-Key: <sua chave>

Não envie Authorization e não envie company-id. A empresa (tenant) é derivada da própria chave: cada chave pertence a exatamente uma empresa, e o Aston resolve o contexto a partir dela. Se você enviar company-id com um valor diferente da empresa da chave, a requisição é recusada com 403.

2. Como gerar uma chave

1. Use um usuário que tenha a permissão Editar Integrações.
2. No Aston, vá em Configurações → Integrações → Chaves de API.
3. Clique em Nova chave, informe um nome que identifique o consumidor (ex.: ERP do cliente X) e, opcionalmente, uma data de expiração.
4. Copie a chave gerada. Ela começa com ast_ e é exibida uma única vez: depois de fechar a tela, a listagem mostra apenas o prefixo (os 12 primeiros caracteres), que serve só para você reconhecer qual chave é qual.
5. Guarde a chave como um segredo (variável de ambiente, cofre de senhas). Se ela vazar ou o consumidor for desativado, use Revogar na listagem — a revogação invalida a chave imediatamente, sem período de carência.

Perdeu a chave? Não há como recuperá-la. Gere uma nova e revogue a antiga.

3. Exemplo

curl -H "X-API-Key: ast_..." https://<host>/partners/

4. Limites e erros

• Sem escopos. A chave tem acesso total aos dados da empresa que a gerou. Não há chave "somente leitura" nem restrição por recurso — trate-a como credencial de acesso completo àquela empresa.
• Rotas negadas para chaves de API (respondem 403 em qualquer método): /auth, /users, /invites e /api-keys — e também POST /companies. São fluxos centrados em usuário humano e a gestão das próprias chaves; devem ser feitos pelo painel.
• 401 — chave ausente, inválida, expirada ou revogada.
• 403 — rota negada para chaves de API, ou header company-id divergente da empresa da chave.

5. Paginação

As listagens aceitam os parâmetros de query:

Exemplo: GET /partners?page=0&size=50 ou GET /partners?paginated=false.