Api Auth — SoliDB Docs

Authentication

On first startup, an admin user is created with a randomly generated password shown in the server logs. Save this password!

How to send credentials

Authorization: Bearer <jwt> — the default for API calls.
X-API-Key: <key> — long-lived programmatic access.
?token=<jwt> — WebSocket upgrades only.

A token in a query string ends up in access logs, proxy logs and browser history, so it is accepted on exactly three paths — /_api/ws/changefeed, /_api/cluster/status/ws and /_api/monitoring/ws — where the browser WebSocket API cannot send a header. Every other endpoint answers 401 and logs the attempt, including /_api/livequery/token, the REST endpoint that issues these short-lived tokens.

POST /auth/login

Authenticate and receive a JWT token.

Request Body Options

Field	Type	Description	Required
username	string	Username (e.g., "admin").	Yes
password	string	User's password.	Yes

Response

200 OK application/json

{ "token": "eyJhbGciOiJIUzI1NiIsInR..." }

PUT /_api/auth/password

Change current user's password.

Request Body Options

Field	Type	Description	Required
current_password	string	Current password.	Yes
new_password	string	New password.	Yes

Response

200 OK application/json

{ "status": "password_updated" }

POST /_api/auth/api-keys

Create a new API key.

Request Body Options

Field	Type	Description	Required
name	string	Name/Description for the API key.	Yes
roles	array	List of role names to assign to this key (e.g. ["editor", "viewer"]). Defaults to empty.	No
scoped_databases	array	Restrict key access to specific databases (e.g. ["mydb", "analytics"]). Omit for unrestricted access.	No

Response

200 OK application/json

{ "id": "uuid-v4-...", "name": "My API Key", "key": "sk_...", "created_at": "2023-...", "roles": ["editor"], "scoped_databases": ["mydb"] }

GET /_api/auth/api-keys

List active API keys.

Response

200 OK application/json

{ "keys": [ { "id": "...", "name": "...", "created_at": "..." } ] }

DELETE /_api/auth/api-keys/:key_id

Revoke an API key.

Response

200 OK application/json

{ "deleted": true }

GET /_api/livequery/token

Generate a short-lived JWT token for WebSocket live query connections. This token expires in 30 seconds. Useful for connecting to real-time changefeeds without exposing long-lived admin tokens.

Response

200 OK application/json

{ "token": "eyJhbGciOiJIUzI1NiIsInR...", "expires_in": 30 }

Usage: Call this endpoint, then connect to ws://host:6745/_api/ws/changefeed?token=TOKEN

Note: this endpoint itself is a normal REST call — authenticate it with an Authorization: Bearer header or X-API-Key. A token passed as ?token= is rejected here with 401; the query parameter is only accepted on the WebSocket upgrade paths listed below.

GET /_api/auth/me

Get current authenticated user info and roles.

Response

200 OK

{ "username": "admin", "roles": ["admin"], "permissions": [...] }

GET /_api/auth/me/permissions

Get effective permissions for the current user.

Response

200 OK

{ "permissions": [{"action": "admin", "scope": "global", "database": null}] }

Roles (RBAC)

Role-Based Access Control. Builtin roles: admin, editor, viewer.

GET /_api/auth/roles

List all roles. Requires admin permission.

Response

[{ "name": "admin", "description": "Full system access", "permissions": [...], "is_builtin": true }]

POST /_api/auth/roles

Create a custom role. Requires admin permission. Role names cannot start with reserved prefixes (admin, editor, viewer).

Request Body Options

Field	Type	Description	Required
name	string	Name of the custom role.	Yes
description	string	Human-readable description.	No
permissions	array	List of permission objects. Each has: `action` (admin\|write\|read), `scope` (global\|database), `database` (required if scope is database).	Yes

Example

{ "name": "analyst", "description": "Read-only analyst", "permissions": [{"action": "read", "scope": "database", "database": "analytics"}] }

GET /_api/auth/roles/:name

Get a specific role by name.

PUT /_api/auth/roles/:name

Update a custom role. Cannot modify builtin roles.

Request Body Options

Field	Type	Description	Required
description	string	Updated description for the role.	No
permissions	array	Updated list of permission objects. Each has: `action` (admin\|write\|read), `scope` (global\|database), `database` (required if scope is database).	No

DELETE /_api/auth/roles/:name

Delete a custom role. Cannot delete builtin roles.

Users

User management endpoints. All require admin permission.

GET /_api/auth/users

List all users with their roles.

Response

{ "users": [{ "username": "admin", "created_at": "2025-01-01T00:00:00Z", "roles": ["admin"] }] }

POST /_api/auth/users

Create a new user.

Request Body Options

Field	Type	Description	Required
username	string	Username (1-64 characters).	Yes
password	string	Password (minimum 6 characters).	Yes
initial_role	string	Role to assign immediately. Must reference an existing role.	No

DELETE /_api/auth/users/:username

Delete a user.

GET /_api/auth/users/:username/roles

Get roles assigned to a user.

Response

{ "roles": [{ "id": "uuid", "role": "admin", "database": null, "assigned_at": "..." }] }

POST /_api/auth/users/:username/roles

Assign a role to a user.

Request Body Options

Field	Type	Description	Required
role	string	Name of an existing role to assign.	Yes
database	string	Limit role to a specific database. Omit or set to null for global assignment.	No

DELETE /_api/auth/users/:username/roles/:role

Revoke a role from a user.

Query Parameters

Parameter	Type	Description	Required
database	string	Revoke role for a specific database scope. Omit to revoke global assignment.	No

Cluster