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:
| Credencial | Onde vale | Em nome de quem |
|---|---|---|
| Token de login | Em toda a API, exceto nas três rotas da API de e-mail transacional que pedem chave | Do 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_TOKENO 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
refreshTokenjá 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
| Rota | O que faz |
|---|---|
GET /auth/sessions | Lista 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/logout | Encerra a sessão do token usado na chamada. Com {"sessionId": "..."} no corpo, encerra essa sessão. |
POST /auth/logout-all | Encerra 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
| Status | message | Quando acontece |
|---|---|---|
401 | Missing authorization | Nenhum token foi enviado. |
401 | Invalid or expired token | O token não é válido ou já expirou. Renove e tente de novo. |
401 | Token revoked | A sessão do token foi encerrada. |
401 | Invalid credentials (código AUTH_INVALID_CREDENTIALS) | E-mail ou senha errados, no login. |
429 | código AUTH_RATE_LIMIT_EXCEEDED | Muitas 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-keyscom o token de login de quem tem a permissãoapi_keys:create. - Permissões da chave:
email:send(enviar) eemail: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 envieX-Workspace-ID. - Validade: não expira. Vale até ser revogada (
DELETE /api-keys/{id}, com a permissãoapi_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
refreshTokenem vez de repetir o login a cada chamada; o login tem limite de tentativas. - Encerre a sessão com
POST /auth/logoutquando a integração deixar de usá-la. - Crie uma chave de API por sistema. Assim, revogar uma não derruba as outras.
Updated 17 days ago