Users Databases

List Database Users

GET /v1/databases/{uuid}/users

List a database's users, oldest first. Apps connect to a database as one of its users. A database can have up to 10 users. Passwords are never listed: one is returned only by the call that creates the user or rotates its password. Requires Databases read.

User object

uuid string (uuid)

The user's id.

name string

Your label, unique on this database.

db_user string

The generated login, u_<6 characters>_<name>. An app connected as the user gets it as DB_USER.

access string

read_write: SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, ALTER, INDEX, CREATE VIEW, SHOW VIEW on this database. read_only: SELECT, SHOW VIEW.

kind string

customer.

status string

provisioning (being created) → ready; rotating (a new password is being set); failed (last_error says why; rotating its password retries); deleting.

password_rotated_at string (RFC 3339)

The last password rotation; absent if the password was never rotated.

database_uuid string (uuid)

The database.

used_by array

The apps connected as this user, {application_uuid, application_name}. Several apps can share a user (and then share its connection and query-rate caps).

created_at / updated_at string (RFC 3339)

Timestamps.

Response (200 OK)

{"users": […], "max_users": 10}. max_users is the most users a database can have.

Errors

403

No Databases read, no active account, or no managed databases on the plan.

404

database not found.

503

databases_unavailable.

Request
curl "https://api.ngris.com/v1/databases/019c2a41-7d3e-7b52-a1c4-5e9f0b3d6a18/users" \
  -H "X-API-KEY: <your_api_key>"

Response — 200 OK
{
  "users": [
    {
      "uuid": "019c2a41-7d40-7e15-9b63-2f8c4d1a7e95",
      "name": "app",
      "db_user": "u_p7d2m1_app",
      "access": "read_write",
      "kind": "customer",
      "status": "ready",
      "created_at": "2026-10-18T09:00:00Z",
      "updated_at": "2026-10-18T09:00:04Z",
      "database_uuid": "019c2a41-7d3e-7b52-a1c4-5e9f0b3d6a18",
      "used_by": [
        { "application_uuid": "019be838-d261-7d9b-9499-71995a3a91c6", "application_name": "orders-api" }
      ]
    }
  ],
  "max_users": 10
}

Create Database User

POST /v1/databases/{uuid}/users

Add a user to a database. ngris generates its login and a 48-character hex password, and returns the password once, in this response; it is stored encrypted and never returned again. Apps connected as the user get it automatically. The user starts as provisioning and becomes ready within seconds (once the database is ready). Requires Databases write.

Request body

name string

Required. 1–32 characters, no control characters, not starting with _, unique on this database.

access string

read_write (default) or read_only.

Response (201 Created)

{user, password, password_notice}: the new user, its password (shown only in this response) and a reminder that it is shown once.

Errors

400

invalid request body, User name must be 1-32 characters, with no control characters, not starting with _, or Access must be read_write or read_only.

403

No Databases write, no active account, or no managed databases on the plan.

404

database not found.

409

name_taken: A user with this name already exists on this database.
user_limit: A database can have at most 10 users. (with limit: 10).
quota_paused: the database is paused over your plan's database limit; a paused database gets no new users.
database_status: the database is failed or deleting (e.g. Not possible while the database is deleting., with resource and status).

503

databases_unavailable.

Request
curl -X POST "https://api.ngris.com/v1/databases/019c2a41-7d3e-7b52-a1c4-5e9f0b3d6a18/users" \
  -H "X-API-KEY: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "reporting", "access": "read_only" }'

Response — 201 Created
{
  "user": {
    "uuid": "019c2a60-3b1c-7f48-b2d9-6c0e5a8f1d34",
    "name": "reporting",
    "db_user": "u_k3x9p2_reporting",
    "access": "read_only",
    "kind": "customer",
    "status": "provisioning",
    "created_at": "2026-10-18T09:10:00Z",
    "updated_at": "2026-10-18T09:10:00Z",
    "database_uuid": "019c2a41-7d3e-7b52-a1c4-5e9f0b3d6a18",
    "used_by": []
  },
  "password": "<48 hex characters, shown once>",
  "password_notice": "This password is shown only once. ngris stores it encrypted and never shows it again — rotate the user's password if you lose it."
}

Response — 409 (user limit)
{
  "error": "A database can have at most 10 users.",
  "code": "user_limit",
  "limit": 10
}

Delete Database User

DELETE /v1/databases/{uuid}/users/{user_uuid}

Delete a user: it is marked deleting and ngris drops its login. The delete is refused while any application connects as the user; disconnect those apps (or connect them as another user) first. Works on a paused database too, and answers 202 again for a user already being deleted. Requires Databases delete.

Response (202 Accepted)

{"user": {…}} with status: "deleting".

Errors

403

No Databases delete, no active account, or no managed databases on the plan.

404

database not found or database user not found.

409

database_user_in_use: apps connect as this user; connected_apps lists them.

503

databases_unavailable.

Request
curl -X DELETE \
  "https://api.ngris.com/v1/databases/019c2a41-7d3e-7b52-a1c4-5e9f0b3d6a18/users/019c2a60-3b1c-7f48-b2d9-6c0e5a8f1d34" \
  -H "X-API-KEY: <your_api_key>"

Response — 409 (in use)
{
  "error": "This user is used by 1 application: disconnect it (or switch it to another user) first.",
  "code": "database_user_in_use",
  "connected_apps": [
    { "application_uuid": "019bf0a1-5c2e-7a90-9d13-8e4f6b2a1c07", "application_name": "reports" }
  ]
}