Auth Strategies

Impersona needs a predictable way to identify the current user for each request. Choose the strategy that matches your app's auth model.

Strategy A: Authorization header swap (JWT / API token)

Best for: APIs that authenticate with Authorization: Bearer <token>.

How it works:

• Impersona replaces the Authorization header on API requests.
• Your host reads the token and builds the user context as usual.

Pros:

• Minimal backend changes
• Works well with JWT or API tokens

Cons:

• If your frontend uses other auth headers, you must make sure the swap is safe

Strategy B: Custom Impersona header

Best for: Apps that want explicit opt-in behavior.

How it works:

• Impersona sends a dedicated header (e.g. X-Impersona-Token).
• Your host checks that header first and uses it to resolve the impersonated identity.
• If the header is missing, your host falls back to the normal auth flow.

Pros:

• Clear separation between normal auth and impersonation
• Easy to gate by environment or role

Cons:

• Requires a small server change

Strategy C: Cookie-based session

Best for: Apps that authenticate via cookies (session-based auth).

How it works:

• Impersona sends a token in a header.
• Your host creates or resolves a session for the impersonated user.

Pros:

• Works with existing session middleware

Cons:

• Requires server-side integration

Recommended decision flow

• If you use Bearer tokens: start with Strategy A.
• If you want an explicit impersonation gate: choose Strategy B.
• If you rely on cookie sessions: implement Strategy C.