Governance

Principals, roles, data grants and administrative permissions on a NYXDB node, and how operators review them.

Governance decides what an authenticated session may do. Identity comes from Authentication; this page covers the permissions attached to it.

Deny by default

A new principal starts with no permission. A freshly created user's SELECT answers 403 until an administrator binds a role that grants relation_read; the same read then succeeds.

Roles and data grants are typed commands

Roles and grants are consensus-owned catalog state:

Principals: users created with CREATE USER, and the node's configured bootstrap identity.
Roles: named and non-recursive.
Role bindings: one principal bound to one role.
Role grants: one data action, such as relation_read or relation_write, at tenant scope or on one exact relation.

They are administered through typed administrative commands of the public administration protocol, for example CreateDatabaseRole, GrantDatabaseRole and BindDatabaseRole, sent over a WebSocket session. There is no SQL GRANT, REVOKE or CREATE ROLE for users and roles. The only SQL GRANT names an application access; see Federation.

Administrative permissions

Administrative statements and commands check named administrative actions. The ones a reader of these pages meets most often:

Action	Admits
`credential_manage`	Managing other principals' users and API keys; application-access DDL.
`data_grant_manage`	`GRANT` and `REVOKE` to an application access.
`source_manage`	Every source-management statement: sources, application accesses, their grants, credential import.
`telemetry_read`	Reading telemetry relations such as `system.query_history`, `system.query_stats` and `system.settings`.
`governance_read`	Reading principals, roles, role bindings, grants, credentials and application accesses.
`audit_read`	Reading `system.audit_log`.

Read and manage permissions are separate: a console role that only reads can be granted telemetry_read and governance_read without any manage action. Federation statements check source_manage or the per-operation action. The read permission of every administrative system relation is listed on System relations.

Review what is granted

Relation	Shows
`system.database_principals`	Principals.
`system.roles`, `system.role_bindings`, `system.grants`	Roles, who holds them, and what they grant.
`system.administrative_grants`	Administrative permissions.
`system.credentials`	Credentials per principal, without digests or secrets.
`system.application_accesses`	Application accesses and their grants.
`system.audit_log`	Audited administrative and credential decisions.

The relation names come from the engine's registry; see System relations.

Operator checklist

Create one user per person or service; use KIND SERVICE for services.
Prefer API keys with EXPIRES IN for automation, and drop keys you no longer use.
Grant reads through a role, scoped to the relations a principal needs.
Keep the issuer key file (gateway.issuer.ed25519_private_key_file) readable only by the node process; without it the password and API-key routes answer 404.
After a rotation or a drop, confirm in system.credentials that the old credential is disabled.