> ## Documentation Index
> Fetch the complete documentation index at: https://docs.craftkit.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Refresh an embed session

> POST /v1/embed/sessions/refresh — rotate a session token with its single-use renew token.

<Info>**POST** `https://api.craftkit.dev/v1/embed/sessions/refresh`</Info>

Rotate a session's token before it expires. The `renewToken` is **single-use**: each call mints a
fresh `session_token`, extends `expires_at` by 4 hours, and returns a new `renew_token` — the old
one stops working. The response shape is identical to
[Create a session](/api-reference/create-session).

## Authorization

<ParamField header="Authorization" type="string" required>
  `Bearer ck_live_…` — must be an API key from the **same project** that minted the session.
</ParamField>

## Body

<ParamField body="renewToken" type="string" required>
  The `renew_token` from the last mint or refresh (min 8 chars).
</ParamField>

<Warning>
  Refresh resolves the session by `(project, renewToken)`. A valid key from a **different** project
  will not find the session and returns `401 refresh_failed`. A renew token that was already
  rotated, or a session that is no longer active, also returns `401 refresh_failed` — re-mint in
  that case.
</Warning>

## Response

`200` with the rotated session (same fields as the mint response).

<ResponseField name="session_id" type="string">Unchanged — the original session UUID.</ResponseField>
<ResponseField name="session_token" type="string">A freshly signed EdDSA JWT.</ResponseField>
<ResponseField name="iframe_url" type="string">Builder URL carrying the new token.</ResponseField>
<ResponseField name="expires_at" type="string">New ISO-8601 expiry, 4 hours out.</ResponseField>
<ResponseField name="renew_token" type="string">New single-use renew token; the previous one is invalidated.</ResponseField>

## Errors

| Status | code                    | Meaning                                                                        |
| ------ | ----------------------- | ------------------------------------------------------------------------------ |
| 401    | `missing_authorization` | No `Authorization: Bearer` header.                                             |
| 401    | `invalid_credentials`   | Key not found, revoked, or embed not enabled.                                  |
| 400    | `invalid_json`          | Body is not valid JSON.                                                        |
| 422    | `invalid_request`       | `renewToken` missing or shorter than 8 chars.                                  |
| 401    | `refresh_failed`        | Renew token invalid/already rotated, session inactive, or wrong project's key. |

```bash cURL theme={null}
curl -X POST https://api.craftkit.dev/v1/embed/sessions/refresh \
  -H "Authorization: Bearer $CRAFTKIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "renewToken": "ert_8sR2...Xq" }'
```

```json 200 theme={null}
{
  "session_id": "0193c2c3-1a2b-7c3d-8e4f-aabbccddeeff",
  "session_token": "eyJhbGciOiJFZERTQS...",
  "iframe_url": "https://embed.craftkit.dev/embed/builder?session_token=eyJhbGciOiJFZERTQS...",
  "expires_at": "2026-06-05T18:00:00.000Z",
  "renew_token": "ert_9tT3...Yz"
}
```