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

Typescript (SDK)

TypeScript

import { Unkey } from "@unkey/api";

const unkey = new Unkey({
  rootKey: process.env["UNKEY_ROOT_KEY"] ?? "",
});

async function run() {
  const result = await unkey.portal.createSession({
    slug: "my-portal",
    externalId: "user_123",
    permissions: [
      "api.*.read_key",
      "api.*.create_key",
      "api.*.read_analytics",
    ],
  });

  console.log(result);
}

run();

200

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

Authorizations

Authorization · string · header · required

Unkey uses API keys (root keys) for authentication. These keys authorize access to management operations in the API. To authenticate, include your root key 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. Key permissions follow a hierarchical structure with patterns like resource.resource_id.action (e.g., apis.*.create_key, apis.*.read_api). 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 · string[] · required

List of RBAC tuple permissions defining what the end user can do in the Portal. Each permission is a string in the format {resourceType}.{resourceId}.{action}. Use * as resourceId to grant access to all resources of that type.

Tab visibility is derived from the action segment:

• Keys tab: read_key, create_key, update_key, delete_key
• Analytics tab: read_analytics
• Docs tab: visible when any permission is present

Minimum array length: 1

Pattern: ^[^.]+\.[^.]+\.[^.]+$

Example:

[
  "api.*.read_key",
  "api.*.create_key",
  "api.*.read_analytics"
]

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