Refreshing an expiring session

Sessions & devices

Access tokens are short-lived (default 600s). The client trades the refresh token for a new pair before/after expiry. One channel only: cookie clients get a rotated Set-Cookie, body clients get it in the body.

POST /v1/auth/refresh → new accessToken (refresh token rotated)

POST/v1/auth/refreshpublicRefresh tokens

Cookie clients: the refresh_token cookie set at login rides along automatically — send {}. Body clients: put { refreshToken } in the body. The new accessToken is auto-captured. REUSE DETECTION: replaying an already-used refresh token revokes the ENTIRE session (401) — the expected signal of a stolen/duplicated token. If the session's membership became inactive → 403. Refresh NEVER triggers a device challenge: it is a re-mint of an existing authentication, not a new one, and the device decision is structurally unreachable from this path (the same holds for switch-tenant). This route answers 404 wherever MULTI_APP_ENABLED is on — leaving it reachable would leave a second, UNSCOPED way to renew beside the scoped per-app one (scenario 19).

Request body (JSON)

ℹ︎Field guide — what each value means & where it comes from1 field

Rotates the refresh token and mints a new access token on a single channel (AUTH-IAM-02). Cookie clients send the refresh_token cookie (auto-relayed by the proxy) and get a rotated Set-Cookie with nothing in the body; non-cookie/body clients omit the cookie and instead supply refreshToken in the body and receive the rotated token back. No Authorization header is needed — this endpoint bears the refresh token itself.

refreshTokenbodystringconditionalfrom a response

Provide ONLY when you are a body (non-cookie) client — omit it entirely if the refresh_token cookie is being relayed by the proxy. Not freely typed: paste the refreshToken value returned by a prior response (e.g. the body-channel response of login or a previous refresh). 1–4096 chars. Used to authenticate and rotate the session's refresh token.

→ POST https://api.kerja.team/v1/auth/refresh

↩︎Response guide — what comes back & what each value means4 fields

200 OK with the standard { data } envelope; Cache-Control: no-store. On the cookie channel the rotated refresh token is delivered via Set-Cookie: refresh_token and is NOT echoed in the body; on the body channel (no cookie) the rotated refreshToken is returned in data. data always carries the new accessToken, tokenType, and expiresIn.

data.accessTokenJWTalways

The newly minted access token. Auto-captured by the tester as the active bearer token for subsequent authenticated calls.

data.tokenTypeenumalways

The token scheme to use in the Authorization header.

Bearer — Send the access token as 'Authorization: Bearer <accessToken>'.

data.expiresInintegeralways

Lifetime of the access token in seconds (e.g. 600 = 10 minutes). Use it to schedule the next refresh before expiry.

data.refreshTokenstringconditional

The rotated refresh token, returned ONLY on the body channel (when the caller supplied refreshToken in the request rather than the refresh_token cookie). On the cookie channel it is omitted and delivered via Set-Cookie instead. Store it and present it on the next refresh; the old token is now marked used and reuse will revoke the whole session.