authentication

Authentication

Phase 1 · design: design-phase-1-auth.md

Harness Nexus has a small, explicit permission model: two roles, two token channels, one registration switch.

Roles

• admin — can mutate global-scope resources and manage users.
• user — works on personal-scope resources; reads global ones.

Each user has exactly one role. All access decisions branch on it.

Login channels (both Authorization: Bearer …)

Channel	Form	Used by
JWT access token	signed token, default 7-day lifetime	the web UI
Personal access token (PAT)	hnpat_<random>, stored as sha256	CLI, daemon, automation

PATs can carry scopes. Besides the general API kind there is a marketplace-scoped PAT (kind: 'marketplace') that is accepted only by the Claude Code plugin-marketplace emitter URL and rejected everywhere else — see Profiles & installation.

Registration & bootstrap

• POST /api/auth/register is gated by a system setting (default: open).
• The first user to register becomes the bootstrap admin; admins can create users directly at any time.

Safety rails

• Last-admin protection — the final admin cannot be deleted or demoted.
• No self-delete.
• Disabled users are rejected on every protected request (fresh user lookup per request — disabling takes effect immediately).

Scoping

Resources, profiles, credentials, MCP servers and LLM providers share one scope model: global is readable by any authenticated user but admin-only to mutate; personal is owner-only for everything. Not-found is answered with 404 (never 403) so existence is not leaked across owners.