# 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](/docs/concepts/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](/docs/sql/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](/docs/operations/system-tables).

## 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](/docs/operations/system-tables).

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

---

Source: https://nyxdb.io/docs/operations/governance/