Sign in
OpenAPI 3.1.0raw.githubusercontent.com2026-08-1983295742.1 KB

060c53b503ce

portal

Create portal session

Create a portal session for an end user and get the URL to redirect them to.

The URL carries a single-use exchange code valid for 15 minutes, which the portal redeems exactly once for a 24-hour access token via portal.exchangeCode.

Required Permissions

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

post/v2/portal.createSession

Request body

portalstring required

Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.

externalIdstring required

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

scopesstring[] 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, 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 scopes:

  • Keys tab: any keys:* scope
  • Analytics tab: analytics:read
  • Docs tab: visible when any scope is present
previewboolean

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

returnUrlstring uri

Absolute URL the end user is sent back to when they leave the portal, or when their session expires mid-visit. Set per session rather than per portal, so one portal can serve several entry points and return each user to the page they came from.

When omitted, the portal shows no return link.

Example request

{
  "portal": "proj_1234abcd",
  "externalId": "user_123",
  "scopes": [
    "keys:read",
    "keys:reroll",
    "analytics:read"
  ],
  "returnUrl": "https://app.example.com/settings/api-keys"
}

Response

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

Example response

{
  "meta": {
    "requestId": "req_123"
  },
  "data": {
    "id": "ps_abc123def456",
    "url": "https://portal.unkey.com/?code=pst_abc123def456"
  }
}