---
title: "Exchange session token"
method: POST
path: "/v2/portal.exchangeSession"
tags: ["portal"]
---

# Exchange session token

`POST /v2/portal.exchangeSession`

Exchange a short-lived session token for a long-lived browser session.

This endpoint is unauthenticated. The session token itself serves as proof of authorization.
Each token can only be exchanged once; subsequent attempts return 401.

The returned browser session token is valid for 24 hours and should be stored as an
httpOnly cookie or used in the Authorization header for subsequent API calls.

## Request body

- V2PortalExchangeSessionRequestBody
  - `sessionId` string, required — The session token ID received from `portal.createSession`. Must be valid, unexpired, and not previously exchanged.

## Response `200`

Session exchanged successfully. Use the returned token for subsequent API calls.

- V2PortalExchangeSessionResponseBody
  - `meta` Meta, required — Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The `requestId` is particularly important when troubleshooting issues with the Unkey support team.
    - `requestId` string, required — A unique id for this request. Always include this ID when contacting support about a specific API request. This identifier allows Unkey's support team to trace the exact request through logs and diagnostic systems to provide faster assistance.
  - `data` V2PortalExchangeSessionResponseData, required
    - `token` string, required — The browser session token. Store this as an httpOnly cookie for subsequent portal requests.
    - `expiresAt` integer, required — Unix timestamp in milliseconds when the browser session expires (24 hours from creation).

## Other responses

- `400` — Bad request
- `401` — Unauthorized — session is invalid, expired, or already exchanged
- `429` — Too Many Requests
- `500` — Internal server error

---

[API](https://skmtc.net/unkeyed/apis/unkey-api.md) · [All operations](https://skmtc.net/unkeyed/apis/unkey-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/unkeyed/unkey-api/revisions/4bd11a7252bc/schema)