Autenticação e chaves de API

Chaves de API Bearer, permissões, os requisitos do titular da chave, validade, rotação e revogação.

Estado da API pública

A API v1 usa chaves bearer da empresa e exige um período de plano ativo. Os endpoints de rascunhos e de comunicação de pagamentos não enviam mensagens a clientes. Os exemplos usam marcadores — nunca cole uma chave real em código partilhado.

Chaves Bearer

Envie a sua chave no cabeçalho Authorization de cada pedido:

HTTP

GET /v1/receivables HTTP/1.1
Host: api.remindcash.com
Authorization: Bearer <your-api-key>
Accept: application/json

Os pedidos sem uma chave válida devolvem 401 unauthenticated.

Permissões

Cada chave tem uma ou mais permissões (scopes). Um pedido fora das permissões da chave devolve 403 forbidden.

Permissão	Permite
`receivables:read`	`GET /receivables`, `GET /receivables/{id}`, `GET /reminder-attempts`
`receivables:write`	`POST /receivables`, `PATCH /receivables/{id}`, pagamentos, pausar, retomar, cancelar
`usage:read`	`GET /usage`
`payables:read`	`GET /payables`, `GET /payables/{id}`
`payables:write`	`POST /payables`, `PATCH /payables/{id}`, `POST /payables/{id}/mark-paid`

Dê a cada integração apenas as permissões de que precisa.

Quem pode usar uma chave

Uma chave atua em nome da pessoa que a criou, dentro de uma empresa. Cada pedido verifica que:

o e-mail do titular da chave está verificado e a autenticação de dois fatores está confirmada,
o titular da chave continua a ser um membro ativo da empresa,
a própria empresa está ativa.

Se alguma verificação falhar, o pedido devolve 403 forbidden. Por isso, remover um membro da equipa interrompe de imediato as suas chaves.

Criar, rodar e revogar chaves

As chaves são geridas na aplicação em Definições → Chaves de API pelos proprietários e administradores da empresa com autenticação de dois fatores.

Uma chave nova é mostrada uma única vez; o RemindCash guarda apenas um hash.
As chaves expiram 30 dias depois de emitidas.
Rodar emite uma chave nova com o mesmo nome e as mesmas permissões e apaga a antiga de imediato. Atualize o seu cofre de segredos antes de rodar.
Revogar apaga uma chave de imediato.
Cada pessoa pode ter até 10 chaves ativas por empresa.

Manter as chaves seguras

Guarde as chaves num gestor de segredos ou numa variável de ambiente, nunca no controlo de versões nem no código do front-end.
Use chaves separadas para sistemas separados, para poder revogar uma sem afetar as outras.
Se uma chave puder ter sido exposta, revogue-a imediatamente nas Definições.