POST /api/v1/auth/refresh-token — Rotate auth tokens

Exchange a valid refresh token for a new access and refresh token pair. Old refresh token is invalidated after a successful rotation.

Call this endpoint when the access token expires — by default after 15 minutes — to obtain a new token pair without prompting the user to log in again. You can supply the refresh token in the request body or rely on the HttpOnly cookie set during login when useCookies was true.

POST /api/v1/auth/refresh-token

Authorization: None required. The refresh token itself acts as the credential for this endpoint.

Request body

refreshToken · string

The refresh token returned by /auth/login or a previous call to this endpoint. If omitted, the server reads the token from the refresh_token HttpOnly cookie.

useCookies · boolean

When true, the new access and refresh tokens are also written to the response as HttpOnly cookies. If refreshToken was omitted (cookie-based flow), the cookies are always updated regardless of this flag.

Responses

200 OK — AuthResponseDto

accessToken · string

A new signed JWT access token. The previous access token is not explicitly revoked, but it will expire naturally.

refreshToken · string

A new refresh token. The old refresh token is invalidated immediately upon successful rotation — store the new value right away.

400 Bad Request — ProblemDetails

Returned when the refresh token is invalid, has already been used, or has expired. The user must log in again to obtain a new token pair.

Refresh tokens are single-use. Once rotated, the previous token cannot be used again. If you receive a 400 on a refresh attempt, discard the stored token and redirect the user to the login flow.

Token rotation

The server invalidates the submitted refresh token immediately on a successful response. Your client must:

1. Receive the 200 response.
2. Replace the stored refresh token with the new value in the response.
3. Replace the stored access token with the new value.

If the rotation request fails mid-flight (network error, timeout), the old token may or may not have been consumed. Retry with the same token — if it returns 400, it was already rotated on the server and you need to re-authenticate.

Implement automatic token refresh in your HTTP client. On a 401 response from any authenticated endpoint, call POST /api/v1/auth/refresh-token, update your stored tokens, and then retry the original request exactly once.

Example

curl -X POST https://localhost:5001/api/v1/auth/refresh-token \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "<your-refresh-token>"
  }'