# Autenticação e chave

```
Authorization: Bearer <chave>
```

- A chave alcança **uma empresa** e **só a admissão**, e tem um **nome** dado
  pelo escritório (por exemplo, "ERP da matriz").
- A admissão feita por ela é da **integração da empresa**, não de uma pessoa: o
  histórico do colaborador no Motor diz "Admitido pela chave de API ‹nome›". A
  chave vale enquanto não for revogada e o escritório que a gerou atender a
  empresa — a saída de quem a gerou não a derruba.
- Quem gera e revoga é o **administrador do escritório** que opera a empresa no
  Motor. A chave aparece **uma vez**: guarde-a num cofre de segredos. O Motor
  guarda só o resumo dela e um prefixo para reconhecê-la.
- Revogada, ela deixa de valer **na chamada seguinte** (`401 CHAVE_REVOGADA`).
- Login de usuário e token OAuth do Motor são recusados nestas rotas.

## Limite de uso

60 chamadas por minuto por chave. Acima disso, `429 LIMITE_EXCEDIDO` com
`Retry-After` (em segundos). Não é limite de plano: a admissão conta como
colaborador ativo, como a feita pelo Motor.

## O webhook

O **endereço do webhook** (HTTPS, nunca rede privada) e o **segredo do webhook**
são da **integração da empresa**, não de cada chave: o escritório os cadastra uma
vez, e o segredo também aparece uma vez. Trocar a chave não muda nenhum dos dois.

O webhook é **opcional**: sem ele a chave admite normalmente, e você acompanha
pela consulta (`GET /v1/admissoes/{id}`). Ver [Avisos](https://developers.motorcontabil.com/avisos).

## Trocar a chave sem parar

A empresa pode ter **até duas chaves ativas** ao mesmo tempo, justamente para
isto:

1. Peça ao escritório uma **chave nova**. A antiga continua valendo.
2. Troque a chave no seu sistema. As duas funcionam durante a troca, e a
   consulta (`GET /v1/admissoes/{id}`) responde com qualquer chave ativa da
   empresa — inclusive para admissões enviadas pela antiga.
3. Quando **não houver nada em andamento** pela chave antiga (nenhuma admissão
   dela fora de `PROCESSADA`, `RECUSADA` ou `DESCARTADA`), peça a revogação dela.

> Se a chave for revogada com admissão ainda não transmitida, essa admissão
> **não é enviada sem clique**: cai na fila do escritório e sai o aviso
> `admissao.aguardando_escritorio`. Revogar existe para cortar um canal que pode ter
> sido comprometido, e o que entrou por ele espera uma pessoa aprovar.