Skip to main content
A Ephra usa duas credenciais com papéis diferentes. Entender a distinção evita os erros 401 mais comuns.

API key

Sua credencial permanente (public + secret), gerada uma vez no painel. Serve apenas para fazer login.

Token de acesso

Um Bearer token de curta duração, obtido a cada login. É ele que autoriza as chamadas /v1/*.

​
Por que duas credenciais?

A API key é o seu segredo de longo prazo — como uma senha mestra: quase nunca muda e deve ficar guardada no servidor. Mandar esse segredo em toda requisição seria arriscado, então você o troca por um token temporário. Se um token vazar, ele expira sozinho em pouco tempo.
O secret da API key só aparece uma vez, no momento da criação. Guarde-o num cofre de segredos. Se perder, gere uma nova chave.

​
Ciclo de vida do token

1

Login

Você envia a API key (via HTTP Basic) para POST /auth e recebe um token.
2

Uso

Inclui o token no header Authorization: Bearer <token> de cada chamada /v1/*.
3

Expiração

O token vale pelo tempo indicado em expiresIn (em milissegundos). Depois disso, você faz login de novo.
Cada login abre uma sessão. Um token cuja sessão não existe mais é rejeitado com 401, mesmo que ainda não tenha expirado. Reaproveite o mesmo token enquanto ele for válido, em vez de logar a cada chamada.

​
Boas práticas

  • Faça login uma vez e reutilize o token até perto de expiresIn.
  • Trate 401 como sinal para refazer o login e repetir a chamada.
  • Nunca exponha o secret no front-end — toda chamada autenticada sai do seu back-end.

Referência: POST /auth

Parâmetros, headers e formato de resposta da rota de login.