Authentication Overview

Every request to the hzel API is resolved through a single ordered chain:

1. Session cookie (__Host-hzel_session) — browser-based login via OIDC.
2. Bearer token (Authorization: Bearer <token>):
   • Prefix hzel_ → Personal Access Token (PAT), looked up by SHA-256 hash.
   • Otherwise → JWT access token (OIDC session or OAuth application token).

The first method that succeeds wins. Unauthenticated requests receive 401 UNAUTHORIZED.

Auth methods at a glance

Method	How to send	CSRF required?	OAuth apps can use?
Session cookie	Set automatically by browser	Yes for mutating routes	No
PAT	Authorization: Bearer hzel_…	No	No
JWT (OIDC)	Authorization: Bearer <jwt>	No	No
JWT (OAuth)	Authorization: Bearer <jwt>	No	Yes

Roles

Accounts have one of two roles:

• admin — full platform access including audit logs and all users’ containers.
• user — access to their own containers and resources only.

OAuth application tokens are always downgraded to user effective role, even when the authorizing account is an admin.