Neuwerk

Get Admin Access

Bootstrap a short-lived admin token with the CLI, exchange it for a browser session, or use SSO and cluster auth flows.

Use this guide when you need to access the web UI or management API as an administrator.

For a first-time operator, the recommended bootstrap path is:

  1. use console or SSH access to the Neuwerk node
  2. mint a short-lived admin token locally with the CLI
  3. exchange that token for a browser session in the UI
  4. create a longer-lived automation token only after normal admin access is working

Other practical access paths are:

  1. use an existing bearer token directly with the API
  2. exchange an existing bearer token for a browser session
  3. log in through SSO if an admin-mapped provider is already configured
  4. mint a temporary admin token through the cluster auth CLI in clustered deployments

Bootstrap A First Admin Token On A Single Node

If you have console or SSH access to a single-node appliance, mint a short-lived human admin token directly from the local HTTP auth keyset:

umask 077
sudo neuwerk auth token mint \
  --sub operator@example.com \
  --roles admin \
  --ttl 30m \
  --http-tls-dir /var/lib/neuwerk/http-tls > neuwerk-admin.jwt

Why this is the recommended single-node bootstrap:

  • it only requires operator access to the node itself
  • it does not depend on pre-existing API credentials
  • it mints a short-lived JWT signed by the same local auth material the HTTP API already trusts
  • it avoids keeping a long-lived human admin token around longer than necessary

Use a human-readable subject in --sub such as an email address. Keep the TTL short. After login, create a service account for automation and stop reusing the bootstrap token.

You can then use the token directly:

export NEUWERK_TOKEN="$(cat neuwerk-admin.jwt)"
curl -sk \
  -H "Authorization: Bearer $NEUWERK_TOKEN" \
  https://neuwerk.example/api/v1/auth/whoami

Use A Bearer Token Directly

If you already have a valid admin token, send it with:

Authorization: Bearer <token>

Verify the token and its roles with:

GET /api/v1/auth/whoami

Protected POST, PUT, and DELETE requests require the admin role.

Create A Browser Session From A Token

If you want to use the web UI, exchange the token for a session cookie:

curl -sk \
  -H 'Content-Type: application/json' \
  -X POST \
  https://neuwerk.example/api/v1/auth/token-login \
  --data '{"token":"Bearer '"$NEUWERK_TOKEN"'"}'

On success, the Neuwerk sets the neuwerk_auth cookie and returns the decoded identity.

Use SSO When It Is Already Configured

If the Neuwerk already has an SSO provider configured, use the normal UI login flow.

Admin access through SSO depends on the provider mapping rules. Your identity must match the configured admin subjects, groups, or email-domain rules for that provider.

After login, confirm the assigned roles with:

GET /api/v1/auth/whoami

Mint A Temporary Admin Token In Cluster Mode

Clustered deployments expose an auth administration CLI that can mint tokens through the cluster RPC layer.

Example:

neuwerk auth token mint \
  --sub operator@example.com \
  --roles admin \
  --cluster-addr 10.0.0.11:9600

Notes:

  • --roles admin is what makes the token usable for admin writes
  • --cluster-tls-dir defaults to /var/lib/neuwerk/cluster/tls if you do not override it
  • the command prints the raw token to standard output

Use this path for bootstrap and break-glass access in clustered deployments.

Create An Automation Token From An Existing Admin Session

Once you already have admin access, create a service account for automation:

  1. create the account
  2. mint a token for it
  3. store the returned token securely

Create the account:

POST /api/v1/service-accounts
{
  "name": "terraform",
  "description": "automation account",
  "role": "admin"
}

Mint a token:

POST /api/v1/service-accounts/{id}/tokens
{
  "name": "ci",
  "ttl": "24h",
  "role": "admin"
}

The raw token value is returned only once. Later list operations return token metadata, not the secret value.

Next Steps