---
title: "Exchange portal code"
method: POST
path: "/v2/portal.exchangeCode"
tags: ["portal"]
---

# Exchange portal code

`POST /v2/portal.exchangeCode`

Exchange a short-lived code for a long-lived portal access token.

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

The returned access 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

- V2PortalExchangeCodeRequestBody
  - `code` string, required — The exchange code carried by the portal URL from `portal.createSession`. Must be valid, unexpired, and not previously redeemed.

## Response `200`

Code exchanged successfully. Use the returned access token for subsequent API calls.

- V2PortalExchangeCodeResponseBody
  - `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` V2PortalExchangeCodeResponseData, required
    - `accessToken` string, required — The portal access token. Store this as an httpOnly cookie for subsequent portal requests.
    - `expiresAt` integer, required — Unix timestamp in milliseconds when the access token expires (24 hours from creation).

## Other responses

- `400` — Bad request
- `401` — Unauthorized — code is invalid, expired, or already redeemed
- `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/060c53b503ce/schema)