UNunkeyed
portal

Create portal session

Changed on

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

Authorization runs in two stages, and both must pass.

First, your root key must have one of the following permissions:

  • portal.*.create_portal_session (to mint sessions for any portal in the workspace)
  • portal.<portal_id>.create_portal_session (to mint sessions for a specific portal)

Second, a session can never carry a capability your root key does not itself hold. Each requested scope additionally requires the equivalent permission on every keyspace the portal resolves to:

  • keys:read requires api.<api_id>.read_key and api.<api_id>.read_api
  • keys:reroll requires api.<api_id>.create_key, plus api.<api_id>.encrypt_key when the keyspace stores encrypted keys
  • analytics:read requires api.<api_id>.read_analytics

The * form of each is also accepted. Requesting a scope you do not hold returns 403 for the whole request rather than minting a reduced session, so a missing grant is visible instead of surfacing later as a broken portal.

Missing the portal permission itself returns 404 when your root key cannot read the portal or its sessions, so a caller who cannot see a portal is not told whether it exists. A root key that can read the portal but lacks the permission gets 403.

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

post/v2/portal.createSession

Request

  • Base URL
    https://api.unkey.com
  • URL
    https://api.unkey.com/v2/portal.createSession
  • Auth
    HTTP bearer

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. An end user can never see another identity's keys.

Rerolling and usage analytics are both reached from the keys page, so keys:reroll and analytics:read each require keys:read in the same session; requesting either without it is rejected.

Each scope requires the equivalent permission on your own root key. See Required Permissions on this operation.

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"
  ],
  "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=pec_abc123def456"
  }
}

Changes