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

passwordPOST /auth/password

API keyPOST /auth/api-key

short-lived Ed25519 bearer

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.

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.

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.