Impersona Docs
Impersona Docs
HomePricingImpersona SDKQuickstartInstallationAuth StrategiesPermissions TestingTroubleshooting

IntegrationsDirectus IntegrationOutline IntegrationStrapi Integration

Troubleshooting

Common issues and fixes when integrating Impersona.

The widget loads but impersonation does not work

  • Confirm your host reads the impersonation header or swapped Authorization token
  • Verify the token is valid and maps to a real user
  • Check that your backend logs show the impersonated user context

The widget does not load

  • Verify your publishable key and API base URL
  • Check network requests for blocked CORS

Permission checks look wrong

  • Confirm your backend permissions are enforced server-side
  • Verify you are testing the correct role or attributes
  • Inspect caching layers (tokens, role caches, policy caches)

Cookies and sessions are not recognized

  • Cookie-based sessions require a server integration that converts an Impersona token into a session
  • Ensure the session cookie is set on the correct domain and path

Unexpected 401s or 403s

  • Confirm the host is reading the correct header
  • Verify the Authorization header is not being overwritten by another client
  • Check that environment allowlists include your local domain

Permissions Testing

Validate role-based and attribute-based access control with Impersona.

Integrations

Product-specific guides for using Impersona with popular platforms.

On this page

The widget loads but impersonation does not workThe widget does not loadPermission checks look wrongCookies and sessions are not recognizedUnexpected 401s or 403s