Authentication

NodeDB supports multiple authentication methods simultaneously.

Password Auth (SCRAM-SHA-256)

CREATE USER alice WITH PASSWORD 'strong_password';
CREATE USER IF NOT EXISTS alice WITH PASSWORD 'strong_password';
CREATE USER bob WITH PASSWORD 'secret' ROLE readonly;
DROP USER alice;
DROP USER IF EXISTS alice;

CREATE USER ... IF NOT EXISTS and DROP USER ... IF EXISTS make user DDL idempotent.

psql -h localhost -p 6432 -U alice

API Keys

API keys enable programmatic access for services and applications:

CREATE API KEY FOR alice [EXPIRES <seconds>] [WITH SCOPES '<scope>', ...] [WITH DATABASES (<db1>, <db2>)];
LIST API KEYS FOR alice;        -- or SHOW API KEYS FOR alice
REVOKE API KEY <key_id>;

FOR <user> is mandatory
Key is shown once; store it securely
EXPIRES is seconds until revocation (optional)
WITH SCOPES restricts operations (e.g., 'read:collections', 'write:data')
WITH DATABASES restricts collection access (optional; empty = user's default databases)

Example:

curl -H "Authorization: Bearer <api-key>" http://localhost:6480/v1/query \
     -d '{"sql": "SELECT 1"}'

Service Accounts

Service accounts are privileged accounts designed for application-to-database connections:

CREATE SERVICE ACCOUNT etl_worker FOR DATABASE analytics_db;
ALTER SERVICE ACCOUNT etl_worker SET DATABASES (analytics_db, staging_db);

CREATE API KEY FOR etl_worker WITH DATABASES (analytics_db);

Service accounts are scoped to a single tenant (inherited from the caller) and support per-database access control, inheriting or narrowing their scope when API keys are created on them.

OIDC / SSO

NodeDB supports OpenID Connect (OIDC) for enterprise Single Sign-On integration. See (oidc-sso) for complete configuration, claim mapping, token refresh, and session lifetime management.

OIDC bearer tokens are supported on the native protocol and HTTP entry points only. pgwire connections use SCRAM-SHA-256 exclusively.

JWKS (JWT)

Multi-provider support (Auth0, Clerk, Supabase, Firebase, Keycloak, Cognito):

[auth.jwt]
providers = [{ issuer = "https://your-domain.auth0.com/", audience = "your-api" }]

JWT claims map to $auth.* session variables for RLS:

Claim	Variable	Usage
`sub`	`$auth.id`	`WHERE user_id = $auth.id`
`role`	`$auth.role`	`WHERE $auth.role = 'admin'`
`org_id`	`$auth.org_id`	`WHERE org_id = $auth.org_id`
`scope`	`$auth.scopes`	Scope-based access control
`database_id`	`$auth.database_id`	`WHERE db_shard = $auth.database_id`

Supported algorithms: RS256, ES256.

mTLS

[server.tls]
cert = "/path/to/server.crt"
key = "/path/to/server.key"
client_ca = "/path/to/ca.crt"     # enables mTLS

Auth Priority

mTLS → 2. JWT Bearer → 3. API key → 4. SCRAM-SHA-256