portal_not_found

No portal matched the provided id or slug for your workspace. Verify the identifier or contact Unkey to provision a portal.

err:unkey:data:portal_not_found

Example

{
  "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?

This error occurs when you call POST /v2/portal.createSession with a portal value that does not match a portal in your workspace.

The portal field accepts either the portal’s id (pc_...) or its slug, so this error means neither matched.

Common causes include:

• 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.

Example of a correct request:

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