Sign in
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

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
previewboolean

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

Example request

{
  "slug": "my-portal",
  "externalId": "user_123",
  "permissions": [
    "api.*.read_key",
    "api.*.create_key",
    "api.*.read_analytics"
  ]
}

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"
  }
}

Changes