Sign in

v66

OpenAPI 3.1.0raw.githubusercontent.com2026-08-0174265626.3 KB
portal

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

Request body

slugstring 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.

externalIdstring required

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

permissionsstring[] 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
previewboolean

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

Example request

{
  "slug": "my-portal",
  "externalId": "user_123",
  "permissions": [
    "keys:read",
    "keys:reroll",
    "analytics:read"
  ]
}

Response

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

Example response

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