Autenticação

Como obter, enviar e renovar o token de login, encerrar sessões e usar a chave de API do workspace.

A API aceita duas credenciais:

CredencialOnde valeEm nome de quem
Token de loginEm toda a API, exceto nas três rotas da API de e-mail transacional que pedem chaveDo usuário que fez login, com as permissões que ele tem no workspace
Chave de API do workspace (wsk_)Só em POST /email/transactional/messages, GET /email/transactional/messages e GET /email/transactional/messages/{id}Do workspace

Token de login

Obtenha

POST /auth/login com email e password:

curl -X POST "https://api.vozkoia.com/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "SUA_SENHA"}'

A resposta 200 traz accessToken, refreshToken, tokenType (sempre Bearer) e os dados do usuário (userId, email, name, picture, role, customerType).

Cada login abre uma sessão. A sessão dura 30 dias a partir do login e não é prorrogada pelas renovações: depois desse prazo, é preciso fazer login de novo.

Envie

Envie o accessToken no cabeçalho Authorization, com o esquema Bearer e um espaço:

Authorization: Bearer SEU_ACCESS_TOKEN

O token de acesso é um JWT. Ele expira em 15 minutos na configuração padrão; o instante exato está no campo exp do próprio token, em segundos Unix. Prefira ler o exp, ou renovar quando receber 401, a fixar um prazo no seu código.

As conexões de tempo real também aceitam o token no parâmetro token da URL, porque navegadores não enviam cabeçalhos ao abrir um WebSocket. Nas chamadas HTTP, use sempre o cabeçalho.

Renove

POST /auth/refresh com o refreshToken:

curl -X POST "https://api.vozkoia.com/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "SEU_REFRESH_TOKEN"}'

A resposta tem o mesmo formato do login, com um novo accessToken e um novo refreshToken. A cada renovação o refreshToken é trocado:

  • Passe a usar o novo assim que recebê-lo.
  • O anterior ainda é aceito por 30 segundos depois da troca, para que duas renovações simultâneas não falhem.
  • Depois disso, apresentar um refreshToken já trocado é tratado como roubo: a chamada é recusada e todas as sessões do usuário são encerradas.

Um refreshToken desconhecido, de uma sessão encerrada ou expirada, recebe 401 com a mensagem Invalid refresh token.

Sessões

RotaO que faz
GET /auth/sessionsLista as sessões ativas do usuário: id, deviceInfo (o User-Agent do login), ipAddress, location, isCurrent, createdAt e expiresAt.
DELETE /auth/sessions/{sessionId}Encerra uma sessão do usuário.
POST /auth/logoutEncerra a sessão do token usado na chamada. Com {"sessionId": "..."} no corpo, encerra essa sessão.
POST /auth/logout-allEncerra todas as sessões do usuário.

No logout, o token de acesso da sessão encerrada para de valer na hora, mesmo antes de expirar. O logout-all invalida todos os tokens de acesso já emitidos para o usuário.

Recusas de autenticação

StatusmessageQuando acontece
401Missing authorizationNenhum token foi enviado.
401Invalid or expired tokenO token não é válido ou já expirou. Renove e tente de novo.
401Token revokedA sessão do token foi encerrada.
401Invalid credentials (código AUTH_INVALID_CREDENTIALS)E-mail ou senha errados, no login.
429código AUTH_RATE_LIMIT_EXCEEDEDMuitas tentativas de login erradas. Aguarde os segundos do cabeçalho Retry-After.

As recusas de token não trazem code; trate pelo status 401. Veja Erros.

Chave de API do workspace

A chave de API age em nome do workspace e hoje só vale para a API de e-mail transacional. Nas demais rotas, use o token de login.

  • Onde criar: no aplicativo, em Menu lateral › Integrações › Chaves de API, ou por POST /api-keys com o token de login de quem tem a permissão api_keys:create.
  • Permissões da chave: email:send (enviar) e email:read (ler o registro de envios). Escolha só as necessárias.
  • Formato: wsk_, um identificador de 12 caracteres, _ e o segredo. A chave completa aparece uma única vez, na criação; depois só o prefixo (wsk_ e o identificador) fica visível.
  • Como enviar: Authorization: Bearer wsk_.... A chave já identifica o workspace; não envie X-Workspace-ID.
  • Validade: não expira. Vale até ser revogada (DELETE /api-keys/{id}, com a permissão api_keys:delete), e a revogação vale na hora.
  • Limite: até 25 chaves ativas por workspace.

Boas práticas

  • Chame a API a partir do seu servidor. Não coloque senhas, tokens ou chaves em código que roda no navegador ou no aparelho do cliente.
  • Guarde tokens e chaves em um cofre de segredos, nunca no repositório de código.
  • Use um usuário dedicado à integração, com só as permissões de que ela precisa no workspace.
  • Renove o token de acesso com o refreshToken em vez de repetir o login a cada chamada; o login tem limite de tentativas.
  • Encerre a sessão com POST /auth/logout quando a integração deixar de usá-la.
  • Crie uma chave de API por sistema. Assim, revogar uma não derruba as outras.

Did this page help you?