portal_not_found

{
  "meta": {
    "requestId": "req_2c9a0jf23l4k567"
  },
  "error": {
    "detail": "Portal not found.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/data/portal_not_found"
  }
}

​

What Happened?

• Typo in the portal value sent from your backend.
• The portal belongs to a different workspace than the root key you authenticated with.
• The portal has not yet been provisioned for your workspace. The Customer Portal is in early access, and during that period portals are created by the Unkey team on request.

​

How To Fix

1. Verify the identifier: Double-check that portal matches your portal’s id or slug. Slugs are 3–64 characters, lowercase alphanumeric and hyphens, with no leading or trailing hyphen.
2. Check the workspace: Make sure the root key you are using belongs to the same workspace as the portal.
3. Request a portal: If you have not yet been onboarded to the Customer Portal, contact the Unkey team to provision one for your workspace.

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"]
  }'

​

Common Mistakes

• Wrong root key: Using a root key from a different workspace returns this error rather than a 401, because the lookup is workspace-scoped.
• Malformed looks the same as missing: The lookup does not distinguish a mistyped identifier from one that was never provisioned, so My-Portal, my--portal, and -portal all return this error rather than a validation error. Check the spelling of portal before assuming the portal does not exist. Only values the request schema rejects outright return a 400: shorter than 3 characters, longer than 255, or containing anything other than letters, digits, hyphens, and underscores.
• Underscores are only ever ids: Portal slugs never contain an underscore, so a value like my_portal can only match a portal id. It returns this error unless a portal carries exactly that id.

​

Related Errors

• err:unkey:authentication:portal_token_missing - When a portal session token is required but not provided
• err:unkey:authentication:portal_session_not_found - When a portal session is invalid, expired, or already used
• err:unkey:data:workspace_not_found - When the workspace itself cannot be resolved