Skip to main content
POST https://api.craftkit.dev/v1/embed/sessions/refresh
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.

​
Authorization

​
Authorization
string
required
Bearer ck_live_… — must be an API key from the same project that minted the session.

​
Body

​
renewToken
string
required
The renew_token from the last mint or refresh (min 8 chars).
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.

​
Response

200 with the rotated session (same fields as the mint response).
​
session_id
string
Unchanged — the original session UUID.
​
session_token
string
A freshly signed EdDSA JWT.
​
iframe_url
string
Builder URL carrying the new token.
​
expires_at
string
New ISO-8601 expiry, 4 hours out.
​
renew_token
string
New single-use renew token; the previous one is invalidated.

​
Errors

StatuscodeMeaning
401missing_authorizationNo Authorization: Bearer header.
401invalid_credentialsKey not found, revoked, or embed not enabled.
400invalid_jsonBody is not valid JSON.
422invalid_requestrenewToken missing or shorter than 8 chars.
401refresh_failedRenew token invalid/already rotated, session inactive, or wrong project’s key.
cURL
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" }'
200
{
  "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"
}