Skip to content

Passkeys

Pluma's /api/* is gated behind WebAuthn passkeys — phishing-resistant, hardware-backed, no passwords.

When the gate applies

Three soft escapes keep first-time setup from locking you out:

Condition Effect
require_auth = false in config Gate off entirely (dev mode).
loopback_auth_bypass = true (default) Host machine (127.0.0.1 / ::1) skips auth even when required.
No credentials enrolled for the current origin Middleware passes through, so the pair screen + wizard can run before the first enrollment.

Per-origin grace means enrolling on loopback doesn't gate the tailnet URL, and vice versa. Each new origin you reach Pluma at starts in grace until you enrol there.

Enrol your first passkey

Hit Pluma from a browser. If it's a fresh install + a non-loopback origin (tailnet URL, LAN IP), the Pair screen shows immediately. Otherwise:

Settings → Privacy → Passkeys.

  1. Type a device name (defaults to a sensible guess based on your User-Agent — "iPhone", "Mac", "Windows PC").
  2. Click Set up passkey.
  3. Your OS prompts for biometrics (Touch ID, Face ID, Windows Hello) or PIN.
  4. Done. The credential appears in the Enrolled passkeys list below.

RPID collapse on *.ts.net

On *.ts.net hosts, Pluma collapses the RPID to the tailnet parent (e.g. pluma.alice.ts.net → alice.ts.net). One passkey enrolled there works across every tailnet subdomain. So if you later spin up other tailnet services on the same tailnet, the passkey for alice.ts.net covers them all — assuming each service honours the same RPID.

Revoking

Settings → Privacy → Enrolled passkeys → Revoke next to the credential. Immediate effect; subsequent requests from that credential fail auth.

Bearer tokens for scripts

Browsers use WebAuthn sessions; scripts use bearer tokens. The pluma auth login CLI mints one:

pluma auth login --base-url http://localhost:8787
# Prompts your browser, you tap your passkey, the token lands at
# ~/.config/pluma/cli.token

Use it from curl:

curl -H "Authorization: Bearer $(cat ~/.config/pluma/cli.token)" \
  http://localhost:8787/api/conversations

Or set PLUMA_API_TOKEN in your env and any CLI subcommand picks it up.

pluma auth logout removes the stored token; pluma auth whoami prints the active identity.

Bringing back the Pair prompt

If you dismissed the Pair prompt and want it back: Settings → Privacy → Pair prompt → Show pair prompt again. Useful when a new device hits Pluma for the first time and you want it nudged into enrolment.