Authentication

Authentication identifies human and machine users to the platform. Zenvara ships a chain of providers; you enable the ones your organisation uses.

Providers

Provider	For	Notes
Local	Username/password against auth/users.yaml	The default; good for evaluations and small installs.
API Key	Service-to-service	X-API-Key header; scoped to a user or role.
Windows (SSPI)	AD-integrated, Windows-only	Single sign-on with domain credentials.
PAM	Linux-only	Authenticate against the host’s PAM stack.
LDAP	Directory-backed	Bind against an LDAP/AD directory.
OIDC	SSO / federated identity	Standard OpenID Connect; issues JWTs.
Local-socket	Same-host automation	Unix socket / Windows named pipe; auto-auth via kernel peer credential.

When auth is disabled (Auth.Enabled: false), every request runs as an anonymous user with configurable default permissions — convenient for an evaluation, never for production.

Header forms

Two header forms work on every endpoint:

• Authorization: Bearer <jwt> — human-issued sessions and OIDC-issued tokens.
• X-API-Key: <key> — service-to-service.

Cross-provider identity aliases

The same human may sign in via PAM, LDAP, OIDC, and Windows. Cross-provider identity aliases collapse those ids to one canonical Zenvara user — important for personal-overlay credential paths. Alias data lives on StoredUser.Aliases in auth/users.yaml; optional auto-link-by-email is on by default.

The bootstrap admin

On first start with auth enabled, the platform writes a one-time bootstrap admin password to auth/zenvara_bootstrap_password.txt (never git-tracked). Log in with it, create your real admin user, then delete the file.

Where identity lives on disk

auth/
├── users.yaml            # local-provider users + aliases
├── apikeys.yaml          # API keys
├── secrets-policy.yaml   # path-based secret access rules
├── secrets.enc           # encrypted secrets — never git-tracked
└── zenvara_bootstrap_password.txt   # delete after first login

Continue to Roles & API Keys for the permission model, and Security Review for the buyer’s checklist.