# Database Users

> Source: https://developers.cloud66.com/v3/endpoints/database-users/

## List Database Users

URL: https://developers.cloud66.com/v3/endpoints/database-users/#list
Endpoint: GET /stacks/:stack_id/server_groups/:server_group_id/database_users
OAuth scope: public

Returns a paginated collection of database users associated with the specified server group.

Optionally includes password information if the user has edit permissions and explicitly requests it via the `show_password` parameter. This endpoint triggers an asynchronous info retrieval operation to ensure database user information is current.

**Related models:** Database User, Server Group, Pagination

<ResponseCodes 
  codes={[200, 400, 401, 403, 404]}
  overrides={{
    200: "Success - Returns paginated list of database users",
    400: "Bad Request - Server group does not support database operations",
    403: "Forbidden - OAuth token lacks required `public` scope or insufficient permissions for show_password",
    404: "Not Found - Stack or server group not found"
  }}
/>

### Parameters

- `stack_id` (string, optional) — Stack ID
- `server_group_id` (string, optional) — Server group ID
- `page` (string, optional) — Page number for pagination (defaults to 1, minimum 1)
- `show_password` (string, optional) — Include password in response (requires edit permissions)

### Response

```json
{
  "response": [
    {
      "uid": "user_abc123",
      "username": "app_user",
      "databases": ["app_production", "app_staging"],
      "user_type": "application",
      "created_at": "2023-01-15T10:30:00Z"
    },
    {
      "uid": "user_def456",
      "username": "readonly_user", 
      "databases": ["app_production"],
      "user_type": "readonly",
      "created_at": "2023-01-10T14:20:00Z"
    }
  ],
  "count": 2,
  "pagination": {
    "previous": null,
    "next": null,
    "current": 1,
    "per_page": 30,
    "count": 2,
    "pages": 1
  }
}
```

---

## Create Database User

URL: https://developers.cloud66.com/v3/endpoints/database-users/#create
Endpoint: POST /stacks/:stack_id/server_groups/:server_group_id/database_users
OAuth scope: admin

Creates a new database user with the specified username and access to the selected databases.

This operation is performed asynchronously and returns an async action object to track progress. The user will be created with a randomly generated secure password. Only works with server groups that support database operations.

**Related models:** Database User, Database, Async Action, Server Group

The async action can be monitored using the [Get Stack Action](/v3/endpoints/stacks/action-get) endpoint to track the creation progress.

<ResponseCodes 
  codes={[200, 400, 401, 403, 404]}
  overrides={{
    200: "Success - Returns async action to track database user creation",
    400: "Bad Request - Invalid username, user type, or server group does not support database operations", 
    403: "Forbidden - OAuth token lacks required `admin` scope or insufficient permissions",
    404: "Not Found - Stack or server group not found"
  }}
/>

### Parameters

- `stack_id` (string, optional) — Stack ID
- `server_group_id` (string, optional) — Server group ID
- `username` (string, optional) — Database username to create
- `database_ids` (string, optional) — Array of database UIDs to grant access to
- `user_type` (string, optional) — User type - must be one of the supported types

### Request body

```json
{
  "username": "new_app_user",
  "database_ids": ["db_abc123", "db_def456"],
  "user_type": "application"
}
```

### Response

```json
{
  "response": {
    "id": 789,
    "status": "queued",
    "action_type": "database_user_create",
    "resource_type": "database_user",
    "resource_id": null,
    "started_via": "api",
    "started_at": null,
    "finished_at": null,
    "finished_success": null,
    "finished_message": null,
    "created_at": "2023-01-15T10:30:00Z",
    "updated_at": "2023-01-15T10:30:00Z"
  }
}
```

---

## Regenerate Database User Password

URL: https://developers.cloud66.com/v3/endpoints/database-users/#regenerate-password
Endpoint: POST /stacks/:stack_id/server_groups/:server_group_id/database_users/:id/regenerate_password
OAuth scope: admin

Changes the password for the specified database user. 

The new password is automatically generated and securely stored. This operation is performed asynchronously and returns an async action object to track progress. The new password will be available through the database user details once the operation completes.

**Related models:** Database User, Async Action, Server Group

The async action can be monitored using the [Get Stack Action](/v3/endpoints/stacks/action-get) endpoint to track the password regeneration progress.

<ResponseCodes 
  codes={[200, 400, 401, 403, 404]}
  overrides={{
    200: "Success - Returns async action to track password regeneration",
    400: "Bad Request - Server group does not support database operations",
    403: "Forbidden - OAuth token lacks required `admin` scope or insufficient permissions", 
    404: "Not Found - Stack, server group, or database user not found"
  }}
/>

### Parameters

- `stack_id` (string, optional) — Stack ID
- `server_group_id` (string, optional) — Server group ID
- `id` (string, optional) — Database user UID

### Response

```json
{
  "response": {
    "id": 791,
    "status": "queued",
    "action_type": "database_user_password_change",
    "resource_type": "database_user",
    "resource_id": "user_abc123",
    "started_via": "api",
    "started_at": null,
    "finished_at": null,
    "finished_success": null,
    "finished_message": null,
    "created_at": "2023-01-15T10:40:00Z",
    "updated_at": "2023-01-15T10:40:00Z"
  }
}
```

---

## Delete Database User

URL: https://developers.cloud66.com/v3/endpoints/database-users/#delete
Endpoint: DELETE /stacks/:stack_id/server_groups/:server_group_id/database_users/:id
OAuth scope: admin

Permanently removes the specified database user from all associated databases.

<Callout type="warning" title="Permanent Operation">
This operation cannot be undone and will permanently remove the database user's access. The operation is performed asynchronously and returns an async action object to track progress.
</Callout>

**Related models:** Database User, Async Action, Server Group

The async action can be monitored using the [Get Stack Action](/v3/endpoints/stacks/action-get) endpoint to track the deletion progress.

<ResponseCodes 
  codes={[200, 400, 401, 403, 404]}
  overrides={{
    200: "Success - Returns async action to track database user deletion",
    400: "Bad Request - Server group does not support database operations",
    403: "Forbidden - OAuth token lacks required `admin` scope or insufficient permissions", 
    404: "Not Found - Stack, server group, or database user not found"
  }}
/>

### Parameters

- `stack_id` (string, optional) — Stack ID
- `server_group_id` (string, optional) — Server group ID
- `id` (string, optional) — Database user UID

### Response

```json
{
  "response": {
    "id": 790,
    "status": "queued",
    "action_type": "database_user_delete",
    "resource_type": "database_user",
    "resource_id": "user_abc123",
    "started_via": "api",
    "started_at": null,
    "finished_at": null,
    "finished_success": null,
    "finished_message": null,
    "created_at": "2023-01-15T10:35:00Z",
    "updated_at": "2023-01-15T10:35:00Z"
  }
}
```