Impersona SDK
Guides for integrating Impersona into your product.
Impersona lets support and QA teams impersonate users without touching the database. The SDK embeds a lightweight widget in your app that intercepts outgoing API requests and swaps in the right credentials — your backend sees a normal authenticated request from the target user.
How it works
Three systems collaborate during an impersonation session:
| System | Role |
|---|---|
| Impersona Dashboard | Create projects, generate API keys, set allowed origins, manage presets |
| Your App (Host) | Wraps its component tree with ImpersonaProvider and renders the ImpersonaWidget |
| Widget (SDK) | Fetches presets, patches fetch with the impersonation token, triggers a page reload |
The SDK's FetchInterceptorAdapter intercepts outgoing fetch calls and adds headers based on the active preset's auth mode — either replacing the Authorization header (token-passthrough) or adding a custom X-Impersona-Token header (role-based). SDK-internal calls to the Impersona backend are made directly with the publishable key and bypass the adapter entirely.
Setup flow
Integration follows four phases:
- Configure — Sign up, create an org and project, generate an API key, and set allowed origins. All in the Impersona dashboard.
- Bridge — Copy your project ID and publishable key into your app's
.env, install@impersona/sdk, and addImpersonaProvider+ImpersonaWidgetto your component tree. - Verify — Start your dev server and confirm the widget bubble appears. It should fetch presets successfully. If not, check Troubleshooting.
- Use — Create presets in the dashboard (or capture current users via the widget), apply them, and see impersonation take effect on your API calls.
Guides
- Quickstart — get running in minutes
- Installation — prerequisites and setup
- Auth Strategies — choose how identity is passed
- Permissions Testing — validate RBAC and ABAC
- Troubleshooting — common issues
Product-specific notes live in Integrations.
Key configuration values
Every integration depends on a small set of values that must agree across the dashboard, your .env, and the SDK provider:
| Value | Where it lives | What breaks if wrong |
|---|---|---|
| Project ID | Dashboard → .env → projectId prop | 404 on preset fetch |
| Publishable Key | Dashboard → .env → publishableKey prop | 401 in <10ms |
| API Base URL | .env → apiBaseUrl prop | Network/CORS error |
| Allowed Origins | Dashboard + SDK adapter | 403 "Origin not allowed" |
| Exclude Patterns | SDK adapter (auto-set by default) | Auth failures on internal calls |
If the defaults work for your setup, you only need to configure the project ID, publishable key, and allowed origins. See Troubleshooting for diagnosis when values are misaligned.