Create portal session

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.

POST /v2/portal.createSession

Python (SDK)

Python

from unkey.py import Unkey, models


with Unkey(
    root_key="<YOUR_BEARER_TOKEN_HERE>",
) as unkey:

    res = unkey.portal.create_session(slug="my-portal", external_id="user_123", permissions=[
        models.PermissionEnum.KEYS_CREATE,
        models.PermissionEnum.ANALYTICS_READ,
        models.PermissionEnum.KEYS_CREATE,
    ], preview=False)

    # Handle response
    print(res)

200

{
  "meta": {
    "requestId": "req_123"
  },
  "data": {
    "sessionId": "pst_abc123def456",
    "url": "https://portal.unkey.com/?session=pst_abc123def456"
  }
}

Authorizations

Authorization · string · header · required

Unkey uses bearer tokens for authentication. Public integrations use root keys, while the dashboard proxy uses short-lived JWTs. To authenticate, include the token in the Authorization header of each request:

Authorization: Bearer unkey_123

Root keys have specific permissions attached to them, controlling what operations they can perform. Legacy permissions use tuple strings like api.*.create_key; resource permissions use Unkey Resource Names plus actions, like unkey:v1:ws_123:keyspaces/*#create_key. Security best practices:

• Keep root keys secure and never expose them in client-side code
• Use different root keys for different environments
• Rotate keys periodically, especially after team member departures
• Create keys with minimal necessary permissions following least privilege principle
• Monitor key usage with audit logs.

Body

application/json

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.

Required string length: 3 - 64

Pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$

Example:

"my-portal"

externalId · string · required

The end user's identifier in the customer's system. Accepts arbitrary string values (user IDs, emails, UUIDs, etc.).

Required string length: 1 - 256

Example:

"user_123"

permissions · enum<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

Minimum array length: 1

Available options: keys:read, keys:create, keys:reroll, analytics:read

Example:

[
  "keys:read",
  "keys:reroll",
  "analytics:read"
]

preview · boolean · default: false

When true, creates a preview session for testing the portal experience.

Response

200

application/json

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

meta · object · 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.

Show child attributes

data · object · required

Show child attributes