# Clientes

Um cliente é quem envia. Ele tem uma credencial própria (cli_<id> + senha) que vale nos dois canais — HTTP e SMTP — e uma lista de domínios que pode usar como remetente.

Até a v0.7.0 existia um token único, que administrava e enviava. Por isso ele não podia ser entregue a nenhuma aplicação: quem o recebesse poderia enviar por qualquer domínio, e um vazamento obrigaria a trocar o segredo de todas de uma vez. Desde a v0.8.0 os poderes são separados:

Todos os endpoints desta página exigem o token de admin (X-Auth-Token).

# POST /clients

Cria um cliente e devolve a senha em claro — é a única vez que ela existe fora do hash.

curl -X POST http://localhost:8080/clients \
  -H "X-Auth-Token: {TOKEN_ADMIN}" \
  -H 'Content-Type: application/json' \
  -d '{"name": "nfse", "domains": ["minhaempresa.com.br"]}'

{
  "client_id": "cli_a3f9c1d2e4b6",
  "name": "nfse",
  "domains": ["minhaempresa.com.br"],
  "active": true,
  "created_at": "2026-08-02T12:00:00Z",
  "secret": "3f9a1c...48 caracteres hex...",
  "aviso": "guarde a senha: ela não será exibida de novo"
}

A senha é guardada como bcrypt. Não há endpoint para recuperá-la — só rotacionar.

Domínio não configurado é recusado de propósito: um cliente autorizado a um domínio que não existe é um engano silencioso, que só apareceria no primeiro envio.

# GET /clients

{
  "clients": [
    {
      "client_id": "cli_a3f9c1d2e4b6",
      "name": "nfse",
      "domains": ["minhaempresa.com.br"],
      "active": true,
      "created_at": "2026-08-02T12:00:00Z"
    }
  ]
}

A senha nunca aparece aqui.

# GET /clients/{client_id}

Mesmo objeto, um cliente só. 404 se não existir.

# POST /clients/{client_id}/rotate

Gera uma senha nova. A anterior deixa de valer no instante da chamada — não há período de convivência, então troque a configuração da aplicação junto.

{
  "client_id": "cli_a3f9c1d2e4b6",
  "secret": "nova senha em hex",
  "aviso": "a senha anterior parou de funcionar agora"
}

# PUT /clients/{client_id}/domains

Substitui a lista inteira (não acrescenta):

curl -X PUT http://localhost:8080/clients/cli_a3f9c1d2e4b6/domains \
  -H "X-Auth-Token: {TOKEN_ADMIN}" \
  -H 'Content-Type: application/json' \
  -d '{"domains": ["minhaempresa.com.br", "boletos.com.br"]}'

Lista vazia = o cliente não envia por domínio nenhum (mas continua autenticando).

# PATCH /clients/{client_id}

Habilita ou desabilita:

{"active": false}

Desabilitar vale imediatamente: a próxima autenticação já falha, sem esperar expiração de nada.

# DELETE /clients/{client_id}

Remove o cliente. As mensagens que ele já enfileirou continuam o curso.

# Autorização no envio

O domínio do envelope-from precisa estar na lista do cliente. Fora dela, 403 no HTTP e 550 no SMTP.

A verificação roda antes de consultar a configuração de domínios — assim a resposta não revela quais domínios existem para quem não tem acesso a eles.

Autenticação falha com a mesma resposta nos três casos (cliente inexistente, senha errada, cliente desabilitado) e gasta o mesmo tempo. Sem isso, a diferença de tempo de resposta enumeraria clientes.