Authentication

PodWarden API

The PodWarden fleet API supports multiple authentication methods.

OIDC (Primary)

The frontend initiates the OIDC PKCE flow with the configured provider
After successful login, the provider returns an authorization code
The code is exchanged for access and refresh tokens
The access token is sent as a Bearer token on subsequent API requests

Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

Configure your OIDC provider under Settings → System Config → OIDC or via environment variables. Any OpenID Connect provider works: Keycloak, Google, GitHub, Authentik, etc.

Temporary Admin

For initial setup, set PW_TEMP_ADMIN_USERNAME and PW_TEMP_ADMIN_PASSWORD environment variables. This creates a temporary admin account that bypasses OIDC. Remove these variables after creating permanent accounts.

Local Users

Create local user accounts via Settings → Users. Each user has an email, password, and role. Authenticate via the login form — no external IdP required.

MCP Tokens

Machine-readable API tokens for automation and integrations.

Authorization: Bearer pwm_a1b2c3d4e5f6...

MCP tokens:

Start with pwm_ prefix
Have a role (admin, operator, viewer) that determines API access
Can have an expiry (1–365 days)
Include full audit logging (method, path, status code per request)
Can be revoked or reissued from Settings → MCP Tokens

Create tokens via the dashboard or API. The full token is shown once on creation — copy immediately.

Roles

Role	Permissions
`admin`	Full access to all resources, settings, user management, secrets, token creation
`operator`	Manage hosts, clusters, workloads, deployments, storage
`viewer`	Read-only access to all resources

PodWarden Hub API

The Hub catalog API supports two authentication methods.

API Key Authentication

Generate API keys in the PodWarden Hub dashboard. Use them for machine-to-machine access (PodWarden instances fetching catalog templates).

Authorization: Bearer pwc_a1b2c3d4e5f6...

API keys:

Start with the pwc_ prefix
Are shown once on creation — copy immediately
Can be revoked or re-issued from the dashboard
Are scoped to your organization
Track last-used timestamp

JWT Authentication

Dashboard users authenticate via Keycloak OIDC (Google/GitHub social login supported). The JWT token is used for account management, template administration, and dashboard operations.

Dual Authentication on Catalog

The catalog API endpoints accept both methods:

Auth Method	Visibility
Admin JWT	All templates — public, private, all orgs
API key (org)	Public templates + org-owned + private categories with access grant
No auth	Public templates in non-private categories only

# With API key — sees public + org templates
curl -H "Authorization: Bearer pwc_yourkey" \
  https://apps.podwarden.com/api/v1/catalog/templates

# Admin JWT — sees everything
curl -H "Authorization: Bearer eyJhbGci..." \
  https://apps.podwarden.com/api/v1/catalog/templates

# Public only (no auth)
curl https://apps.podwarden.com/api/v1/catalog/templates

Private Category Access

Private categories (is_private = true) are only visible to organizations with an explicit access grant in the catalog_access table. Admins manage access grants via:

Admin → Categories — click the access icon on private categories
Admin → Organizations — click the access icon on any organization
API — POST /api/v1/admin/catalog-access with org_id and category_id