---
title: "Create portal session"
method: POST
path: "/v2/portal.createSession"
tags: ["portal"]
---

# Create portal session

`POST /v2/portal.createSession`

Create a short-lived session token for an end user to access the Customer Portal.

The returned session ID is valid for 15 minutes and can be exchanged exactly once
for a 24-hour browser session via `portal.exchangeSession`. Redirect the end user
to the returned URL to start the portal experience.

**Required Permissions**

Your root key must be associated with a workspace that has an enabled portal configuration.

## Request body

- V2PortalCreateSessionRequestBody
  - `slug` string, required — The human-readable slug of the portal configuration to create the session against. Identifies which app's portal the end user will access. Must be 3-64 characters, lowercase alphanumeric and hyphens only, must not start or end with a hyphen, and must not contain consecutive hyphens.
  - `externalId` string, required — The end user's identifier in the customer's system. Accepts arbitrary string values (user IDs, emails, UUIDs, etc.).
  - `permissions` string[], required — The capabilities granted to the end user in the Portal, from a fixed vocabulary. All capabilities are scoped to this end user: key capabilities (`keys:*`) apply only to keys the end user owns within the keyspace configured on the portal configuration, and `analytics:read` returns only the end user's own verification events. An end user can never see another identity's keys or analytics. Tab visibility is derived from the capabilities: - Keys tab: any `keys:*` capability - Analytics tab: `analytics:read` - Docs tab: visible when any capability is present
  - `preview` boolean — When true, creates a preview session for testing the portal experience.

## Response `200`

Session token created successfully. Redirect the end user to the returned URL.

- V2PortalCreateSessionResponseBody
  - `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` V2PortalCreateSessionResponseData, required
    - `sessionId` string, required — The short-lived session token ID. Valid for 15 minutes and can be exchanged once for a browser session.
    - `url` string, uri, required — The full portal URL with the session parameter. Redirect the end user to this URL.

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `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)