# Managing users and databases

Users (i.e. roles with LOGIN privileges) and databases can be created using the documented SQL commands. The API provides an alternative way to manage these objects.

| Quick Links User Management:                                | Quick Links Database Management:                              |
| ----------------------------------------------------------- | ------------------------------------------------------------- |
| [**List all users**](#list-all-users)                       | [**List all databases**](#list-all-databases)                 |
| [**List system users**](#list-system-users)                 | [**Retrieve a single database**](#retrieve-a-single-database) |
| [**Retrieve a single user**](#retrieve-a-single-user)       | [**Create a database**](#create-a-database)                   |
| [**Create a user**](#create-a-user)                         | [**Remove a database**](#remove-a-database)                   |
| [**Remove a user**](#remove-a-user)                         |                                                               |
| [**Change the login password**](#change-the-login-password) |                                                               |

## Common attributes

Each response from the API will include some standard attributes for metadata and pagination (for collections) which follow the IONOS API standards. Most of these will be omitted from the response examples for brevity.

### Type, ID and Pagination in collections

```json
{
  "_links": {
    "next": "https://link-to-next-collection-page",
    "previous": "https://link-to-previous-collection-page",
    "self": "https://link-to-this-collection-page"
  },
  "href": "http://link-to-this-collection-page",
  "id": "UUID-for-this-collection-page",
  "items": [
    ...
  ],
  "limit": 100,
  "offset": 0,
  "type": "collection"
}
```

### Type, ID and Metadata for resources

```json
{
  "href": "https://link-to-this-resource-page",
  "id": "UUID-for-this-resource-page",
  "metadata": {
    "createdBy": "URN-of-creator",
    "createdByUserId": "UUID-of-creator",
    "createdDate": "creation-timestamp",
    "lastModifiedBy": "URN-of-actor",
    "latModifiedByUserId": "UUID-of-actor",
    "lastModifiedDate": "modification-timestamp",
    "resourceURN": "URN-for-this-resource"
  },
  "properties": {
    ...
  },
  "type": "user-or-database"
}
```

If a resource is:

* not created via the API, its `createdBy` field ends with `_unmanaged_`.
* a read-only system resource, its `createdBy` field ends with `_system_`.

## Managing users

The endpoint for user management of a postgresql cluster is `/users`.

### List all users

A `GET` request will give you a list of all users. Use the `limit` and `offset` parameters to control pagination.

```bash
curl --request GET \
    --user "clientname@ionos.com:Mb2.r5oHf-0t" \
    https://api.ionos.com/databases/postgresql/clusters/498ae72f-411f-11eb-9d07-046c59cc737e/users
```

#### Response

```json
{
  "id": "a580ee24-7cf1-509c-8a40-d716f1e2f187",
  "items": [
    {
      "id": "b35402eb-bd7b-512d-92c9-9726db47c101",
      "properties": {
        "system": false,
        "username": "someuser"
      },
      "type": "user"
    }
  ],
  "limit": 100,
  "offset": 0,
  "type": "collection"
}
```

### List system users

Set the `system` parameter to `true` to view system users too. These users are required for administration purposes and cannot be changed or deleted.

```bash
curl --request GET \
    --user "clientname@ionos.com:Mb2.r5oHf-0t" \
    https://api.ionos.com/databases/postgresql/clusters/498ae72f-411f-11eb-9d07-046c59cc737e/users?system=true
```

#### Response

```json
{
  "id": "c90a5396-1a43-538b-a4c8-564cd0eafc07",
  "items": [
    {
      "id": "6e209957-a468-562e-9867-2a69069044c3",
      "properties": {
        "system": true,
        "username": "ionos_cloud_admin"
      },
      "type": "user"
    },
    {
      "id": "27d4069e-4df9-56cf-8114-1a846589c73a",
      "properties": {
        "system": true,
        "username": "postgres"
      },
      "type": "user"
    },
    {
      "id": "b35402eb-bd7b-512d-92c9-9726db47c101",
      "properties": {
        "system": false,
        "username": "someuser"
      },
      "type": "user"
    },
    {
      "id": "e1ca756d-957e-5e5b-9089-56943078f98c",
      "properties": {
        "system": true,
        "username": "standby"
      },
      "type": "user"
    }
  ],
  "limit": 100,
  "offset": 0,
  "type": "collection"
}
```

### Retrieve a single user

A single user can be retrieved by their name using a `GET` request.

```bash
curl --request GET \
    --user "clientname@ionos.com:Mb2.r5oHf-0t" \
    https://api.ionos.com/databases/postgresql/clusters/498ae72f-411f-11eb-9d07-046c59cc737e/users/someuser
```

#### Response

```json
{
  "id": "b35402eb-bd7b-512d-92c9-9726db47c101",
  "properties": {
    "system": false,
    "username": "someuser"
  },
  "type": "user"
}
```

### Create a user

With the `POST` request, you can create a new user and set the login password.

```bash
curl --request POST \
    --user "clientname@ionos.com:Mb2.r5oHf-0t" \
    --header "Content-Type: application/json" \
    --data-binary '{
        "properties":{
            "username": "newuser",
            "password": "pwMin10Chars"
        }
    }' \
    https://api.ionos.com/databases/postgresql/clusters/498ae72f-411f-11eb-9d07-046c59cc737e/users
```

#### Response

The created user is returned.

```json
{
  "id": "b35402eb-bd7b-512d-92c9-9726db47c101",
  "properties": {
    "system": false,
    "username": "newuser"
  },
  "type": "user"
}
```

### Remove a user

Use a `DELETE` request to remove a user. System users cannot be deleted.

```bash
curl --request DELETE \
    --user "clientname@ionos.com:Mb2.r5oHf-0t" \
    https://api.ionos.com/databases/postgresql/clusters/498ae72f-411f-11eb-9d07-046c59cc737e/users/someuser
```

#### Response

The response body is empty.

### Change the login password

With the `PATCH` request, you can change the login password.

```bash
curl --request PATCH \
    --user "clientname@ionos.com:Mb2.r5oHf-0t" \
    --header "Content-Type: application/json" \
    --data-binary '{
        "properties":{
            "password": "newMin10CharPw"
        }
    }' \
    https://api.ionos.com/databases/postgresql/clusters/498ae72f-411f-11eb-9d07-046c59cc737e/users/someuser
```

#### Response

The updated user is returned. The password is never returned, though.

```json
{
  "id": "b35402eb-bd7b-512d-92c9-9726db47c101",
  "properties": {
    "system": false,
    "username": "someuser"
  },
  "type": "user"
}
```

## Managing databases

The endpoint for database management of a postgresql cluster is `/databases`.

### List all databases

A `GET` request will give you a list of all databases. Use the `limit` and `offset` parameters to control pagination.

```bash
curl --request GET \
    --user "clientname@ionos.com:Mb2.r5oHf-0t" \
    https://api.ionos.com/databases/postgresql/clusters/498ae72f-411f-11eb-9d07-046c59cc737e/databases
```

#### Response

```json
{
  "id": "68b29b09-20e3-5fbc-94bb-b193a2ef0d28",
  "items": [
    {
      "id": "13852d13-dd87-5973-ae2c-12ecc918ee0f",
      "properties": {
        "databasename": "postgres",
        "databaseowner": "postgres"
      },
      "type": "database"
    },
    {
      "id": "d3d34784-1d4c-505f-a4ec-e8f593098ea6",
      "properties": {
        "databasename": "template0",
        "databaseowner": "postgres"
      },
      "type": "database"
    },
    {
      "id": "44e6b542-3f75-5882-8a99-53ee43ac1d97",
      "properties": {
        "databasename": "template1",
        "databaseowner": "postgres"
      },
      "type": "database"
    }
  ],
  "limit": 100,
  "offset": 0,
  "type": "collection"
}
```

### Retrieve a single database

A single database can be retrieved by its name using a `GET` request.

```bash
curl --request GET \
    --user "clientname@ionos.com:Mb2.r5oHf-0t" \
    https://api.ionos.com/databases/postgresql/clusters/498ae72f-411f-11eb-9d07-046c59cc737e/databases/postgres
```

#### Response

```json
{
  "id": "13852d13-dd87-5973-ae2c-12ecc918ee0f",
  "properties": {
    "databasename": "postgres",
    "databaseowner": "postgres"
  },
  "type": "database"
}
```

### Create a database

Use a `POST` request to create a new database. It must specify both the name and the owner.

```bash
curl --request POST \
    --user "clientname@ionos.com:Mb2.r5oHf-0t" \
    --header "Content-Type: application/json" \
    --data-binary '{
        "properties": {
          "databasename": "newdb",
          "databaseowner":"someuser"
        }
    }' \
    https://api.ionos.com/databases/postgresql/clusters/498ae72f-411f-11eb-9d07-046c59cc737e/databases
```

#### Response

The created database is returned.

```json
{
  "id":"57a27d14-3966-5f2d-94ea-2a21086e9d76",
  "properties": {
    "databasename": "newdb",
    "databaseowner":"someuser"
  },
  "type":"database"
}
```

### Remove a database

Use a `DELETE` request to remove a database.

```bash
curl --request DELETE \
    --user "clientname@ionos.com:Mb2.r5oHf-0t" \
    https://api.ionos.com/databases/postgresql/clusters/498ae72f-411f-11eb-9d07-046c59cc737e/databases/newdb
```

#### Response

The response body is empty.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ionos.com/cloud/~/revisions/AMiYziCllTKB2y2lmONY/databases/postgresql/api-howtos/users-databases.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.