Admin & Security

Bootstrap, first-login key rotation, team key management, and recovery.

First boot

On first boot, Waypoint checks whether any API keys exist. If none do, it generates an initial admin key and prints it to the server logs:

═══════════════════════════════════════════════════════════
  Waypoint — First Boot
  Admin API key (shown once — store in your secret manager):

  wp_a1b2c3d4e5f6...

═══════════════════════════════════════════════════════════

Warning

Copy this key immediately and store it in a password manager or secret store. It is shown once and never again.

The initial admin key is marked as requiring rotation. When you log into the web UI with it for the first time, you are redirected to /admin/rotate before you can access anything else.

Here you create a personal admin key with a name you choose. The bootstrap key is revoked, your session cookie is cleared, and you are shown the new key once. Log in with the new key to access the dashboard.

This ensures the anonymous "Initial Admin Key" is never left active in production.

Issuing team keys

Once you're logged in as admin, go to /admin to create keys for your team:

Click Create key
Give it a name (e.g. the developer's name or machine)
Select scopes: sessions:write and sessions:read for regular users; admin:* for admins
Copy the key and give it to the developer — it's shown once

Developers save their key with waypoint connect <server-url>, which prompts for the key and saves it to ~/.waypoint/config.json.

Revoking a key

From /admin, click Revoke next to any active key. Revocation is immediate. The developer's sessions will no longer post to the server, and their get_waypoint_context calls will return 401.

Demo / public mode

Setting WAYPOINT_PUBLIC=true allows unauthenticated read-only access to session pages. The admin panel always requires login. This is useful for demos or open-source projects where you want to share session history publicly.

A yellow banner is shown in the admin panel when public mode is on, with a reminder of how to disable it.

Forgetting the admin key

If the admin key is lost and you cannot log in:

Use the recovery token you set in WAYPOINT_RESET_TOKEN to wipe all API keys:

curl -X POST https://your-server/api/admin/reset-auth \
  -H "Authorization: Bearer <WAYPOINT_RESET_TOKEN>"

The server is now in bootstrap state — all keys are gone
On next server start (or immediately if the server is running), visit the web UI. You'll see the bootstrap form, or a new key will be printed to the logs
Log in and create a permanent key via the rotation flow

Warning

If you did not set WAYPOINT_RESET_TOKEN before deployment and you've lost the admin key, you'll need direct Postgres access to recover. Connect to the database and run DELETE FROM api_keys; — the server will treat the next request as a first boot and print a new bootstrap key to the logs.

Danger zone

The admin panel includes a Danger zone with three irreversible actions. Each requires typing a confirmation phrase before executing.

Action	Phrase	What it does
Revoke all other keys	`revoke all`	Revokes every active API key except yours. Other users lose access immediately.
Delete all session data	`delete sessions`	Permanently deletes all recorded sessions and the file index. API keys are preserved.
Full reset	`full reset`	Deletes all session data AND revokes all other keys. Your key is preserved.

These exist for situations like: cleaning up after a security incident, starting fresh on a project, or decommissioning a server.

PreviousDeployment NextEnterprise Self-Hosting

Search documentation