---
title: "Refresh Token"
method: POST
path: "/auth/refresh"
tags: ["Authentication"]
---

# Refresh Token

`POST /auth/refresh`

## Request

- Base URL: `https://api.getmetacognition.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.getmetacognition.com/auth/refresh`
- Auth: none declared
- TypeScript: <https://skmtc.dev/metacognition/apis/tex-api/docs/auth/refresh/post.ts> (a function with typed inputs; its response is checked against the schema)

Rotate a refresh token into a new token pair.

The new pair reproduces the old identity exactly (org, user, session,
`act` marker, originating key) — never more. Tokens exchanged from an API
key carry its id (`key_id`); that key must still exist, be active and
belong to the token's org, otherwise the chain is dead (revocation used
to be ineffective here because every refresh minted a fresh 7-day token).
Roles are the token's roles narrowed to the key's CURRENT scopes, so a
refresh can drop privileges but never add them.

Refresh tokens without `key_id` (minted before key binding, or by the
DEBUG-only /auth/login) are refused outside DEBUG: they cannot be tied to
a revocable credential. API-key clients re-exchange on 401.

## Request body

- RefreshTokenRequest: Request to refresh access token.
  - `refresh_token` string, required: Refresh token

## Response `200`

Successful Response

- TokenResponse: JWT token response.
  - `access_token` string, required: JWT access token
  - `refresh_token` string, required: JWT refresh token
  - `token_type` string: Token type
  - `expires_in` integer, required: Token expiration in seconds

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/metacognition/apis/tex-api.md) - [All operations](https://skmtc.dev/metacognition/apis/tex-api/llms.txt) - [OpenAPI document](https://skmtc.dev/metacognition/apis/tex-api/revisions/3bef47e50f2e?raw)