Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ricardomb-tech/auth-service/llms.txt

Use this file to discover all available pages before exploring further.

When the access token expires, use this endpoint to obtain a fresh token pair without requiring the user to log in again. Each call consumes the supplied refresh token and returns a brand-new one — this is called refresh-token rotation. The old token is immediately invalidated after a single successful use. If the service detects that an already-consumed token is being presented again, it treats this as a potential token-theft replay attack and revokes the entire family of tokens derived from the same original login session, forcing the user to re-authenticate.

​
POST /auth/refresh

Authentication: None required — the refresh token itself is the credential.

​
Request Body

​
refreshToken
string
required
The opaque refresh token obtained from POST /auth/login or a previous call to this endpoint. Must not be blank.

​
Response — 200 OK

The response shape is identical to POST /auth/login.
​
accessToken
string
A new signed HS256 JWT. TTL: 15 minutes (900 seconds).
​
refreshToken
string
A new opaque refresh token. The previously submitted token is now invalid and must not be used again. TTL: 7 days from this response.
​
tokenType
string
Always "Bearer".
​
expiresInSeconds
number
Always 900.
Example 200 response: 
{
  "accessToken": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI4ZjQyYmM5MS0...",
  "refreshToken": "bmV3T3BhcXVlUmVmcmVzaFRva2VuVmFsdWU=",
  "tokenType": "Bearer",
  "expiresInSeconds": 900
}

​
Error Responses

StatusCondition
401 UnauthorizedToken is not recognised, has already been consumed, has expired, or belongs to a revoked family.
400 Bad RequestThe refreshToken field is missing or blank.
Example 401 response: 
{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Refresh token inválido o expirado.",
  "instance": "/auth/refresh"
}
The error message is deliberately identical for all failure reasons — whether the token is unknown, expired, already used, or part of a revoked family — to prevent leaking state information to an attacker.

​
curl Example

curl -s -X POST http://localhost:8080/auth/refresh \
  -H 'Content-Type: application/json' \
  -d '{
    "refreshToken": "dGhpcyBpcyBhbiBvcGFxdWUgcmFuZG9tIHRva2Vu"
  }'
Reuse detection: Presenting a refresh token that has already been consumed is treated as evidence of a replay attack. The service immediately revokes all tokens in the same family — every refresh token that descends from the same original login session becomes invalid. The user must call POST /auth/login to start a new session. Ensure you replace the stored refresh token with the one returned in each response before discarding the old one.
Refresh the access token proactively — before it expires — rather than waiting for a 401. A good strategy is to schedule a refresh when roughly 80% of the expiresInSeconds TTL has elapsed (i.e. around the 12-minute mark for the default 15-minute TTL). This avoids brief windows where in-flight requests fail due to an expired token.

Build docs developers (and LLMs) love

Get started for freeTalk to us