CSRF Protection

hzel enforces CSRF protection for session-cookie-authenticated mutating requests (POST, PATCH, DELETE). Stateless auth methods (PAT, JWT Bearer) are exempt.

The rule

Auth method	Mutating request (POST/PATCH/DELETE)	Read request (GET)
Session cookie	x-csrf-token required	Not required
PAT (hzel_…)	Not required	Not required
JWT Bearer	Not required	Not required

Getting your CSRF token

Call GET /api/v1/auth/session after login. The response includes a csrf_token field bound to your session:

{
  "data": {
    "session": {
      "csrf_token": "3f2a1b4c-…"
    }
  }
}

Sending the header

Include the token as-is in the x-csrf-token header:

POST /api/v1/containers
x-csrf-token: 3f2a1b4c-…
Content-Type: application/json

Error response

A missing or mismatched CSRF token returns:

403 Forbidden

{
  "error": {
    "code": "CSRF_REJECTED",
    "message": "A valid CSRF token is required for this request"
  }
}

Summary for API clients

If you are building a non-browser client (CLI tool, backend service, mobile app), use a PAT or OAuth access token instead of session cookies. This eliminates the CSRF requirement entirely.