Autenticação da API (credencial de máquina)
Base: https://api.yoobank.net
A credencial de máquina é separada do login humano (cookie + MFA no pay.yoobank.net).
Header
Authorization: Bearer ybk_example...Formato real do token: ybk_{32hex}_{43base64url}.
O prefixo ybk_ nunca é interpretado como sessão humana.
Capacidades da credencial de máquina (únicas):
merchant.payin.createmerchant.payin.read
A credencial pertence a um merchant. O UUID no path tem de ser o desse merchant.
Isolamento
| Situação | HTTP |
|---|---|
| Credencial em falta, malformada, desconhecida ou revogada | 401 AUTH_REQUIRED |
| Credencial válida a aceder a outro merchant, ou sem a capacidade exigida | 403 AUTH_FORBIDDEN |
| Merchant autorizado, intent inexistente ou de outro merchant | 404 NOT_FOUND (sem enumeração) |
Armazenamento
Trate o Bearer como segredo.
Recomendado: variável de ambiente ou gestor de segredos no servidor.
YOOBANK_API_TOKENNunca coloque o token em:
- JavaScript de browser
- repositório público
- HTML
- bundle mobile
localStorage/ cookies de cliente
Exemplos nesta documentação usam placeholders (ybk_example...) ou getenv('YOOBANK_API_TOKEN').
Rotação e revogação
Existem operações de plataforma para criar, rodar e revogar credenciais. Não há portal self-service no dashboard merchant neste checkpoint. Pedir à operação YooBank em caso de compromisso. Depois de suspeita de fuga, revogar e emitir nova credencial.
A YooBank guarda apenas o hash do segredo. Isso não é um detalhe que o merchant precise de replicar.
CSRF
Mutações autenticadas por cookie exigem CSRF. Pedidos com credencial de máquina (Bearer) não usam cookie de sessão e não enviam CSRF.
Cookie e Bearer não podem ser enviados em conjunto.