Authentication

Plugwerk supports two authentication methods:

Local Login (JWT)

Built-in username/password authentication with JWT tokens. Enabled by default.

A superadmin account is created on first start. The password is either:

• Set via PLUGWERK_AUTH_ADMIN_PASSWORD environment variable, or
• Generated randomly and surfaced on two channels that bypass SLF4J so log aggregators (Datadog, ELK, CloudWatch, …) do not capture the bootstrap credential:
  • the container's stderr (direct System.err write, no SLF4J appenders attached)
  • the file /tmp/plugwerk-admin-password.txt inside the container (POSIX mode 0600)

When PLUGWERK_AUTH_ADMIN_PASSWORD is set, both channels stay silent — the credential is already known to the operator.

Retrieving the generated password

Pick whichever channel fits your operational setup. Both work for the Docker Compose stack from Quickstart and the standalone container from Deployment — adjust the service / container name (plugwerk-server below) if you renamed it.

From container stderr (forwarded by docker compose logs / docker logs):

# Docker Compose
docker compose logs --no-log-prefix plugwerk-server | grep -A 6 "Initial Superadmin Password"

# Standalone container
docker logs plugwerk-server 2>&1 | grep -A 6 "Initial Superadmin Password"

From the 0600 file inside the container:

# Docker Compose
docker compose exec plugwerk-server cat /tmp/plugwerk-admin-password.txt

# Standalone container
docker exec plugwerk-server cat /tmp/plugwerk-admin-password.txt

Caution

The generated password is intended only as a one-shot bootstrap credential. The account is flagged passwordChangeRequired, so the first login forces a password change. Do not reuse the generated value as a long-lived credential.

OIDC / OAuth 2.0 Providers

Plugwerk supports browser-based "Sign in with …" login against external identity providers — Keycloak, Auth0, Microsoft Entra ID, Google, GitHub, Facebook, and any generic OAuth 2.0 source. Multiple providers can be enabled simultaneously and appear as buttons on the login page.

See OIDC / OAuth 2.0 Providers for the full setup guide, the provider-specific walkthroughs (creating the client app at the IdP, callback URLs, scopes), the REST API reference, and troubleshooting.

API Key Authentication

For clients, API keys provide read-only access without requiring a login flow:

| Method | Header | Permissions | | ------------ | ----------------------------- | ---------------------------------- | | API Key | X-Api-Key: pwk_... | Read-only (list, search, download) | | Bearer Token | Authorization: Bearer <jwt> | Per user role |

API keys are managed per namespace under Settings → API Keys.