Authentication Overview

EUnifyer uses bearer-token authentication for all external API access. All tokens resolve to a single organization and carry a bounded set of scopes.

Three auth flows

All three token types are accepted on all external API endpoints using the same Authorization: Bearer <token> header.

User-delegated vs machine access

Some APIs — Drive and Sites — operate on per-user data. They require the request to resolve to an acting user. The three flows handle this differently:

The Partner API accepts pure machine identity (no acting user needed).

How tokens are validated

1. The Authorization: Bearer header is extracted.
2. EUnifyer identifies the token type:
   • eu_sk_… prefix → PAT lookup (hashed comparison)
   • RS256 JWT → Keycloak JWKS validation
   • HS256 JWT → first-party session (UI dogfooding)
3. For PATs: expiry, revocation, and IP allowlist checks run.
4. For Keycloak JWTs: azp (client ID) is matched to a service principal; sub is optionally matched to a user.
5. The result is an ApiTokenContext:
   • principal_type — pat, keycloak_jwt, or user_jwt
   • organization_id — always present
   • scopes — intersection of the token’s scopes and the service principal / user’s allowed scopes
   • actor_user_id — the acting user, if any

Token storage and security

• PAT secrets are shown once at creation and never again. Store them securely (a secrets manager, not a .env file in git).
• PATs are stored hashed at rest (SHA-256). EUnifyer cannot recover a lost PAT — rotate instead.
• Keycloak JWTs are short-lived (15 minutes by default) and refreshed using a refresh token or client credentials re-grant.
• All credential events (create, rotate, revoke, use) are recorded in the audit log.

Common header

Authorization: Bearer <your-token>

This is the only supported way to pass credentials to external API endpoints. Cookie-based auth is not supported for external integrations.

Admin UI locations