Renovar e encerrar a sessão
Troca o refresh token por um par novo e encerra a sessão de um aparelho ou de todos.
O token de acesso vence em minutos, por segurança. Em vez de pedir a senha de novo, guarde o refresh_token e troque-o por um par novo antes do vencimento. Quando a pessoa clica em "Sair", encerre a sessão no servidor: só apagar o token no navegador deixa a sessão viva até vencer.
Há dois níveis de saída. logout encerra o aparelho atual e não mexe nos outros. logout-all ("sair de todos os aparelhos") derruba todas as sessões da conta. Trocar ou redefinir a senha também derruba todas.
Renovar
/api/v1/auth/refreshPúblicaTrocar o refresh token por um par novo
A renovação rotaciona o refresh token: o antigo deixa de valer e a resposta traz um novo. Não precisa de Authorization. As regras de login são reaplicadas: se a conta foi desativada, ou a subconta suspensa, ou a loja passou a exigir e-mail verificado, a renovação falha.
Corpo da requisição
refresh_tokenstringobrigatóriorefresh_token mais recente recebido.Exemplo de requisição
curl -X POST "$BASE_URL/api/v1/auth/refresh" \
-H "Content-Type: application/json" \
-d '{"refresh_token":"'"$REFRESH_TOKEN"'"}'Resposta
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refresh_token": "d2f7a1c4b6e8905a3c1e7f9b2d4a6c8e0f1b3d5a7c9e2f4b6d8a0c1e3f5b7d9a",
"expires_at": "2026-10-11T21:25:00Z"
}Campos da resposta
access_tokenstringrefresh_tokenstringexpires_atstringErros da renovação
| Status | Quando | Corpo |
|---|---|---|
| 400 | Corpo inválido ou sem refresh_token | {"error":"refresh_token is required"} |
| 401 | Refresh token desconhecido, vencido ou já usado | {"error":"invalid refresh token","detail":"invalid refresh token"} |
| 401 | Subconta suspensa | {"error":"subaccount_suspended"} |
| 401 | Loja exige e-mail verificado e a conta não verificou | {"error":"email_not_verified"} |
| 429 | Mais de 10 chamadas por minuto do mesmo IP em /auth/ | {"error":"rate limit exceeded",...} |
Sair deste aparelho
/api/v1/auth/logoutAutenticadaEncerrar a sessão deste aparelho
Aceita duas formas. Com refresh_token no corpo, apaga essa sessão e também nega o token de acesso enviado no Authorization, se houver. Só com o Authorization: Bearer, nega aquele token de acesso, mas a sessão de refresh continua; para encerrá-la, mande o refresh token. Sem nenhum dos dois, 400.
Corpo da requisição
refresh_tokenstringAuthorization.Cabeçalhos
AuthorizationstringBearer <access_token>. Opcional se o corpo trouxer o refresh token.curl -X POST "$BASE_URL/api/v1/auth/logout" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"refresh_token":"'"$REFRESH_TOKEN"'"}'{ "message": "logged out" }Sair de todos os aparelhos
/api/v1/auth/logout-allAutenticadaEncerrar todas as sessões da conta
Exige o token de acesso no Authorization. Apaga todas as sessões de refresh da conta e invalida todos os tokens de acesso já emitidos, em todos os aparelhos. Não tem corpo.
Cabeçalhos
AuthorizationstringobrigatórioBearer <access_token>.curl -X POST "$BASE_URL/api/v1/auth/logout-all" \
-H "Authorization: Bearer $TOKEN"{ "message": "logged out of every device" }Erros da saída
| Status | Quando | Corpo |
|---|---|---|
| 400 | logout sem corpo com refresh token e sem Bearer válido | {"error":"logout requires a refresh_token body or a Bearer access token"} |
| 401 | logout-all sem Bearer | {"error":"logout-all requires a Bearer access token"} |
| 401 | logout-all com token inválido | {"error":"invalid token"} |
| 401 | logout-all com token já revogado | {"error":"token revoked"} |
| 500 | Falha ao gravar a saída | {"error":"logout failed","detail":"..."} |