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 code: The exchange code carried by the portal URL is valid for 15 minutes. After that it can no longer be redeemed.
• Already-redeemed code: Codes are single-use. Once the portal redeems one, the same code cannot be redeemed again.
• Expired access token: After exchange, the access token is valid for 24 hours. Once it expires, requests using it return this error.
• Revoked session: A session that has been explicitly revoked returns this error even before its natural expiry.

​

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 '{
    "portal": "my-portal",
    "externalId": "user_123",
    "scopes": ["keys:read", "analytics:read"]
  }'

// 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 code: Codes are single-use. Generate a new session for every redirect.
• Storing codes: Don’t persist exchange codes. They are short-lived credentials meant to be consumed immediately, and they are not recoverable from Unkey once issued.
• Confusing id with the code: portal.createSession returns a non-secret id alongside the url. The id identifies the session for your own records; it is not a credential and cannot be exchanged.
• 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 access token is supplied at all
• err:unkey:data:portal_not_found - When the portal referenced by portal does not exist
• err:unkey:authentication:missing - When no authentication credentials are provided to a non-portal endpoint