Rotate a refresh token family.
POST /auth/token/refresh
POST
/auth/token/refresh
Exchanges a valid refresh token for a new access + refresh token pair. The previous refresh token is immediately invalidated. Presenting a refresh token that has already been rotated (replay) revokes the entire family and returns 401.
Authenticates the caller via the Trusted App key pair (X-API-Key-ID + X-API-Key-Secret) in addition to the refresh token in the body. Binding refresh to the app-level key is defense-in-depth: a leaked refresh token alone cannot be rotated without the issuing app’s credentials.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Header Parameters
Section titled “Header Parameters ” X-API-Key-ID
required
string
Trusted App API key id (format pol_tai_<24 base64url>).
X-API-Key-Secret
required
string
Trusted App API key secret (64 hex). Never logged, never echoed.
Request Body required
Section titled “Request Body required ”object
refreshToken
required
string
Responses
Section titled “ Responses ”New token pair issued.
object
accessToken
required
string
refreshToken
required
string
expiresIn
required
integer
tokenType
required
string
scopes
required
Array<string>
Validation error.
Invalid, expired, replayed, or foreign refresh token.
Rate limit exceeded.