Skip to main content

Documentation Index

Fetch the complete documentation index at: https://unkey.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

err:unkey:authentication:portal_token_missing
Example
{
  "meta": {
    "requestId": "req_2c9a0jf23l4k567"
  },
  "error": {
    "detail": "A portal session token is required for this request.",
    "status": 401,
    "title": "Unauthorized",
    "type": "https://unkey.com/docs/errors/unkey/authentication/portal_token_missing"
  }
}

​
What Happened?

This error occurs when a request was made to an endpoint that requires a Customer Portal session, but no session token was supplied. Portal-authenticated endpoints expect either:
  • An httpOnly session cookie set by the portal after a successful session exchange, or
  • An Authorization: Bearer <portal-session-token> header on direct API calls from a browser session.
Common causes include:
  • The user’s browser has cookies disabled or blocked for the portal domain.
  • The session was never created — the user landed on the portal without going through POST /v2/portal.exchangeSession.
  • A backend integration is calling a portal-only endpoint with a root key instead of a portal session token.
  • The session cookie was cleared or the user opened the portal in a private/incognito window with stripped state.

​
How To Fix

Make sure the user has an active portal session before calling portal endpoints:
  1. From your backend, call POST /v2/portal.createSession with your root key to create a session.
  2. Redirect the user to the returned url. The portal will exchange the short-lived session ID for a 24-hour browser session.
  3. Subsequent requests from the browser must include the portal session cookie or token.
curl -X POST https://api.unkey.com/v2/portal.createSession \
  -H "Authorization: Bearer YOUR_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "my-portal",
    "externalId": "user_123",
    "permissions": ["api.*.read_key"]
  }'
If you are calling the portal API directly from JavaScript, ensure your fetch includes credentials so the session cookie is sent: 
await fetch("https://api.unkey.com/v2/...", {
  credentials: "include",
});

​
Common Mistakes

  • Calling portal endpoints with a root key: Root keys authenticate backend requests, not portal endpoints. Use a portal session.
  • Missing credentials: "include": Cross-origin browser requests omit cookies by default.
  • Expired session not refreshed: After 24 hours the session expires — your backend must create a new one.
  • Direct navigation to the portal: Users must arrive via your backend redirect, not by visiting the portal URL directly.
Last modified on May 8, 2026