portal_session_not_found

{
  "meta": {
    "requestId": "req_2c9a0jf23l4k567"
  },
  "error": {
    "detail": "Session is invalid, expired, or has already been used.",
    "status": 401,
    "title": "Unauthorized",
    "type": "https://unkey.com/docs/errors/unkey/authentication/portal_session_not_found"
  }
}

​

What Happened?

• Expired session ID — The short-lived session ID returned by portal.createSession is valid for 15 minutes. After that it can no longer be exchanged.
• Already-used session ID — Session IDs are single-use. Once a browser exchanges it, the same ID cannot be exchanged again.
• Expired browser session — After exchange, the browser session is valid for 24 hours. Once it expires, requests using that token return this error.

​

How To Fix

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", "api.*.read_analytics"]
  }'

// In your backend route handler
if (request.url.searchParams.get("reason") === "session_expired") {
  const { data } = await createPortalSession(currentUser);
  return Response.redirect(data.url, 302);
}

​

Common Mistakes

• Reusing a session ID: Session IDs are single-use. Generate a new one for every redirect.
• Storing session IDs: Don’t persist session IDs — they are short-lived and meant to be consumed immediately.
• Skipping the exchange: The portal frontend must call portal.exchangeSession to convert the session ID into a browser session.
• Long-running tabs: Users who keep the portal open beyond 24 hours need a fresh session.

​

Related Errors

• err:unkey:authentication:portal_token_missing - When no portal session token is supplied at all
• err:unkey:data:portal_config_not_found - When the portal configuration referenced by slug does not exist
• err:unkey:authentication:missing - When no authentication credentials are provided to a non-portal endpoint