Authentication | PodWarden Hub

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
Carry a role — admin or readonly — 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

PodWarden Core's role is binary. There is no permission matrix and no per-scope capability list: the role by itself is the whole authorization signal.

Role	Permissions
`admin`	Full access to all resources, settings, user management, secrets, token creation
`readonly`	Read access only. Excludes secret values — reading a secret requires `admin`, even though listing is a read.

Earlier releases offered operator and viewer alongside a granular permission matrix. Both were removed when the matrix was retired; a token or user carrying either no longer exists. If you have automation that requests operator, it needs admin — there is no intermediate tier.

PodWarden Hub API

The Hub REST API supports two authentication methods. A third Hub credential — the personal access token — is not a REST credential at all; see Personal Access Tokens below.

Instance Key Authentication

Generate instance keys in the PodWarden Hub dashboard. An instance key is the Core→Hub tunnel key: one per PodWarden Core, a machine credential nobody personally owns. It is what an operator pastes into PodWarden's Settings → Hub, and it is what authenticates machine-to-machine calls to the Hub REST API.

Authorization: Bearer pwh_a1b2c3d4e5f6...

Instance keys:

Start with the pwh_ 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

They authenticate the catalog and support surface: /api/v1/catalog/*, /api/v1/instance-info, DDNS, support tickets, and addon audit events.

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.

Personal Access Tokens

A personal access token (pwp_) is minted by a signed-in human — from Connect an AI client on /dashboard/mcp, or on /dashboard/api-keys — and is scoped to exactly one instance. It is recorded against the minting user, so calls made with it are attributable to a named human. Minting requires only organization member. An expiry is optional (up to 365 days), and tokens are listed, rotated, and revoked from the Access tokens table on the MCP access page. Rotation is restricted to the token's own minter; revocation is additionally available to an organization admin.

No role or permission snapshot is captured on the token — it carries no catalog or platform authority regardless of what its minter holds. Its organization membership is re-checked on every call, so removing the minter from the organization stops the token immediately, and deleting their user account deletes the token with it.

Authorization: Bearer pwp_a1b2c3d4e5f6...

Personal access tokens are the bearer credential an AI/MCP client presents to Hub's MCP endpoint at https://mcp.podwarden.com/mcp — not to the REST endpoints documented here, which refuse them. See Hub MCP Proxy for the connection flow.

Dual Authentication on Catalog

The catalog API endpoints accept both methods:

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

# With an instance key — sees public + org templates
curl -H "Authorization: Bearer pwh_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