Users and API keys

CREATE, ALTER and DROP USER and API KEY — the SQL statements that manage password logins and API keys on a NYXDB node.

Users and API keys are managed with credential statements. The gateway classifies these statements before query history and before the relational parser, so they never reach the query compiler and history records only their redacted form. For how the resulting logins work, see Authentication.

Where credential statements run

On an account session, over HTTP POST /sql or a WebSocket session.
Application sessions read and subscribe; credentials are managed on account sessions.
Managing another principal's users or keys needs the credential_manage administrative permission; a user may create their own API key.

Grammar

Statement	Effect
`CREATE USER name [KIND HUMAN \| SERVICE] PASSWORD ?`	Creates a user with a password. `KIND` defaults to `HUMAN`.
`ALTER USER name PASSWORD ?`	Replaces the password.
`ALTER USER name ENABLE \| DISABLE`	Enables or disables the user.
`DROP USER name`	Disables the user (the same as `ALTER USER name DISABLE`).
`CREATE API KEY label FOR USER name [EXPIRES IN n HOURS \| DAYS]`	Creates an API key and returns its secret once.
`ALTER API KEY label FOR USER name ENABLE \| DISABLE`	Enables or disables the key.
`DROP API KEY label FOR USER name`	Disables the key.

A password is passed as a bound parameter, PASSWORD ?, so it never appears in statement text or history. Names may be quoted ("Data Team").

Create a user

CREATE USER analyst PASSWORD ?;

The password travels as the statement's parameter. User names are unique, and passwords have a minimum length. The new user can log in at POST /auth/password at once but holds no permission until a role grants one; see Governance.

A service principal is declared with KIND SERVICE:

CREATE USER analyst KIND SERVICE PASSWORD ?;

Rotate a password

ALTER USER analyst PASSWORD ?

After the rotation the new password logs in, and the session opened with the old password ends.

Disable and re-enable a user

DROP USER reporter

ALTER USER reporter ENABLE

DROP USER ends every session of the user and disables its password and API keys. ALTER USER … ENABLE lets the user log in again.

Create an API key

CREATE API KEY reporting FOR USER analyst EXPIRES IN 30 DAYS

The result is one row whose api_key column holds the secret, a string that starts with nyxk1.. It is returned once and never stored in readable form. Exchange it for a bearer at POST /auth/api-key.

EXPIRES IN takes a positive count of HOURS or DAYS, up to ten years.
Key labels are unique per user.

Disable an API key

DROP API KEY reporting FOR USER analyst

After the drop the key no longer exchanges for a bearer, and the sessions it opened end on their next operation (401). Sessions opened with the user's password keep working.

Observe credentials

system.credentials lists the credentials of each principal with their kind (for example password and API key) and status. It carries no digest, salt or secret. See System relations.

Users and API keys

On this page