# Authentication

> How a client proves its identity to a NYXDB node — Ed25519 bearers, sessions, password and API-key issuers, revocation and redaction.

Every request to a node runs under a session, and a session is opened from an
Ed25519 bearer. Passwords and API keys do not replace the bearer: they are
issuers that check a secret and issue a short-lived bearer for its principal.

## One verifier, several issuers

- password — POST /auth/password
- API key — POST /auth/api-key
  ↓
- short-lived Ed25519 bearer
  ↓ POST /auth/session
- session

- The bearer is the only credential `POST /auth/session` accepts, and the only
  proof a session revalidates.
- `POST /auth/password` takes a user name and password; `POST /auth/api-key`
  takes an API key. Both answer with a bearer.
- `GET /auth/issuers` lists the issuers the node offers. A node without an
  issuer key (`gateway.issuer.ed25519_private_key_file`) lists none and answers
  the issuing routes with 404.
- Passwords are stored as Argon2id verifiers. An API key's secret is returned
  once, in the result of `CREATE API KEY`, and is never shown again.

## Sessions

`POST /auth/session` exchanges a bearer for a session token. `GET
/auth/session` reports the session, `POST /auth/session/refresh` renews it and
`DELETE /auth/session` closes it; a closed session's token answers 401.
A WebSocket session presents the session token in its first frame, never in the
URL. See [Protocol](/docs/drivers/protocol).

## Users and keys are SQL

Users and API keys are created and changed with SQL statements on an account
session: `CREATE USER`, `ALTER USER`, `DROP USER`, `CREATE API KEY`,
`ALTER API KEY` and `DROP API KEY`. A password is passed as a bound parameter
(`PASSWORD ?`), so it never appears in statement text.
See [Users and API keys](/docs/sql/users-and-keys).

## Revocation

- Disabling or dropping an API key makes its secret fail, and the sessions it
  opened end on their next operation.
- Dropping a user ends every session of that user; `ALTER USER … ENABLE`
  restores the logins.
- Rotating a password with `ALTER USER … PASSWORD ?` makes the old password
  fail and ends the session it opened.

## Failed logins

A wrong password and an unknown user receive the same 401 body. Repeated
failures are throttled: by default the eleventh failure for one credential
within a minute is answered 429 with a `Retry-After` header.

## Redaction

Credential statements are classified before query history. History and traces
record only a redacted form, for example
`CREATE USER "analyst" KIND HUMAN PASSWORD <redacted>`, and no plaintext secret
reaches a log line, an error, a system relation or the data directory.

## Authorization

A new user starts with no permission, and a role grants it reads, writes and
subscriptions. Roles, role bindings and data grants are administered with
`GRANT` and `REVOKE` and with typed administrative commands. See
[Governance](/docs/operations/governance).

---

Source: https://nyxdb.io/docs/concepts/authentication/