---
title: "Create database user"
method: POST
path: "/api/v1/databases/{database_id}/users"
tags: ["Managed Databases"]
---

# Create database user

`POST /api/v1/databases/{database_id}/users`

## Request

- Base URL: `https://api.rafftechnologies.com`
- URL: `https://api.rafftechnologies.com/api/v1/databases/{database_id}/users`
- Auth: API key in header `X-API-Key`

Add a user with read-only or read-write access. The password is returned once in this response; fetch it again later with `GET /api/v1/databases/{database_id}/users/{name}/credential`.

- PostgreSQL, MySQL and ClickHouse. Valkey and Kafka return `501`.
- Name: 3 to 31 characters, lowercase letters, digits and `_`, starting with a letter. Names the engine or Raff use (`raffadmin`, `postgres`, `root`, `admin` and others, and the prefixes `app_` and `fnb_`) are refused.
- Up to 20 users per database. A name in use returns `409`. The database must be `running`.

## Path parameters

- `database_id` string, required

## Request body

- CreateDatabaseUserRequest
  - `name` string, required: 3 to 31 characters. Starts with a lowercase letter, then lowercase letters, digits, or underscores. Names starting with `app_` or `fnb_` are reserved for Raff Apps and Functions.
  - `role` 'readonly' | 'readwrite', required

## Response `201`

User created

- object
  - `success` boolean
  - `user` DatabaseUser
    - `name` string
    - `role` string: What the user can do, in the engine's terms
    - `scope` string: The database, schema, or keyspace the access applies to
    - `kind` 'admin' | 'scoped' | 'binding' | 'system': `admin` = created with the database; `scoped` = added by you; `binding` = managed by Raff for an app or function; `system` = engine internal
  - `password` string: The new user's password

## Other responses

- `400`: Invalid request parameters
- `401`: Authentication required
- `404`: Resource not found
- `409`: Conflicts with what exists, for example a name already in use

## Changes

- **2026-10-11** `89ec42a2108b`: 1 info
  - added the non-success response with the status `409`
- **2026-10-05** `26292956c4b3`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/rafftechnologies/apis/raff-api/changes/api/v1/databases/:database_id/users/post.md)

---

[API](https://skmtc.dev/rafftechnologies/apis/raff-api.md) - [All operations](https://skmtc.dev/rafftechnologies/apis/raff-api/llms.txt) - [OpenAPI document](https://skmtc.dev/rafftechnologies/apis/raff-api/revisions/3d30cde0acb4?raw)