# Authentication

> Phase 1 · design: [design-phase-1-auth.md](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](profiles-and-installation.md).

## 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.