Additional roles API for managed databases

A database with managed SQL roles can have up to ten additional roles next to its owner, runtime and readonly logins. Each additional role has its own generated username, password, access profile and connection limit. See Database roles for the profiles and how to grant a Custom role access. For a single-login database that opted in to additional roles, use the additional roles API for existing databases instead. API access requires Pro or Business. Every endpoint on this page accepts a full-account key or a key scoped to selected databases that includes this database; see Authentication. Every response, including errors, is sent with Cache-Control: no-store. Only the credentials endpoint returns a password.

Method	Path	Purpose
`GET`	`/api/v1/databases/{id}/custom-roles`	List roles
`POST`	`/api/v1/databases/{id}/custom-roles`	Create a role
`PATCH`	`/api/v1/databases/{id}/custom-roles/{roleId}`	Rename a role
`POST`	`/api/v1/databases/{id}/custom-roles/{roleId}/credentials`	Reveal the password
`POST`	`/api/v1/databases/{id}/custom-roles/{roleId}/changes`	Rotate or revoke
`GET`	`/api/v1/databases/{id}/custom-roles/{roleId}/changes/{operationId}`	Read a change
`POST`	`/api/v1/databases/{id}/custom-roles/{roleId}/changes/{operationId}`	Reconcile a change
`POST`	`/api/v1/databases/{id}/custom-roles/{roleId}/delete`	Revoke and remove in one call
`DELETE`	`/api/v1/databases/{id}/custom-roles/{roleId}`	Remove a revoked role
`POST`	`/api/v1/databases/{id}/custom-roles/{roleId}/prepare`	Reconcile an unfinished create
`POST`	`/api/v1/databases/{id}/custom-roles/{roleId}/admit`	Reconcile an unfinished create

{id} and {roleId} must be lowercase UUIDs. Endpoints that take no body reject a non-empty body with 400 VALIDATION_ERROR.

The role object

{
  "roleId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "profile": "custom",
  "displayName": "reporting",
  "accessProfile": "read_only",
  "username": "dbr_550e8400e29b41d4a716446655440000_c1",
  "ordinal": 1,
  "connectionLimit": 2,
  "generation": 1,
  "credentialGeneration": 1,
  "status": "ready",
  "operationId": null
}

Field	Description
`roleId`	Role ID used in the paths on this page
`profile`	Always `custom` for an additional role
`displayName`	Your label for the role, 1–64 characters
`accessProfile`	`read_only`, `read_write` or `custom`
`username`	Generated PostgreSQL login name. It does not change on rename
`ordinal`	Sequence number of the role on this database; not reused
`connectionLimit`	The role’s own PostgreSQL connection limit
`generation`	Role-set generation for the database
`credentialGeneration`	Increases by one each time the password changes
`status`	`reserved`, `ready`, `revoked`, `updating` or `expired`
`operationId`	List only: ID of the pending change while `status` is `updating`, otherwise `null`

reserved means a create has not finished; see Reconcile an unfinished create. updating means a rotation or revocation is pending. expired means the credential’s validity period has ended; it can no longer be revealed or rotated.

List roles

GET /api/v1/databases/{id}/custom-roles
Authorization: Bearer <api-key>

200 OK

{
  "roles": [
    {
      "roleId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "profile": "custom",
      "displayName": "reporting",
      "accessProfile": "read_only",
      "username": "dbr_550e8400e29b41d4a716446655440000_c1",
      "ordinal": 1,
      "connectionLimit": 2,
      "generation": 1,
      "credentialGeneration": 1,
      "status": "ready",
      "operationId": null
    }
  ]
}

Roles are ordered by ordinal. Revoked roles are left out unless you add ?includeRevoked=true. Removed roles are never listed.

Create a role

POST /api/v1/databases/{id}/custom-roles
Authorization: Bearer <api-key>
Idempotency-Key: <stable-unique-key>
Content-Type: application/json

{
  "displayName": "reporting",
  "accessProfile": "read_only",
  "connectionLimit": 2
}

The body must contain exactly these three fields:

Field	Rules
`displayName`	String, 1–64 characters after trimming, no control characters, unique among the database’s roles
`accessProfile`	`read_only`, `read_write` or `custom`
`connectionLimit`	Integer of 1 or more, checked against the database’s role connection budget

The Idempotency-Key header is required: 1–200 characters, without line breaks or NUL characters, and not starting with dbhost-internal-. A successful create finishes setup in the same call and returns the role as ready. The response contains no password; use Reveal the password.

200 OK

{
  "roleId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "profile": "custom",
  "displayName": "reporting",
  "accessProfile": "read_only",
  "username": "dbr_550e8400e29b41d4a716446655440000_c1",
  "ordinal": 1,
  "connectionLimit": 2,
  "status": "ready"
}

All three profiles get CONNECT on the database and can log in immediately. read_only also gets SELECT and read_write gets DML. A custom role gets no table grants; grant access from your migrations as the owner role. DBHost never grants an additional role CREATE or TEMPORARY. Reuse the same idempotency key after a timeout or an uncertain result. The same key with the same body returns the same role and resumes its setup; the same key with a different body returns 409 MANAGED_ROLE_CONFLICT. Creation is refused with 409 MANAGED_ROLE_CONFLICT when:

the database already has ten roles. Revoked roles still count; delete one to free its slot
the display name is already in use
another role on the database is still reserved, or a credential change on the database is unfinished
a restore of the database is in progress
the database is not active
the database would have four or more additional roles, or the new limit takes the total above the database’s role budget, and the database has no effective server connection cap

If the CONNECT grant was withdrawn during setup, the response is 409 CONNECT_GRANT_REQUIRED with the SQL the database owner can run, then retry the same request:

409 Conflict

{
  "error": {
    "code": "CONNECT_GRANT_REQUIRED",
    "message": "Database owner must grant CONNECT before admitting this role.",
    "databaseName": "my-app",
    "username": "dbr_550e8400e29b41d4a716446655440000_c1",
    "grantSql": "GRANT CONNECT ON DATABASE \"my-app\" TO \"dbr_550e8400e29b41d4a716446655440000_c1\";"
  }
}

A database cloned from a backup that predates additional-role support returns 409 CUSTOM_ROLE_REQUIRES_V3_CLONE. Make a new clone from a newer backup of the source database before adding roles.

Rename a role

PATCH /api/v1/databases/{id}/custom-roles/{roleId}
Authorization: Bearer <api-key>
Content-Type: application/json

{"displayName":"bi-reporting"}

The body must contain exactly displayName, with the same rules as on create. Only the label changes; the username, password and grants stay the same. The role must be ready or revoked.

200 OK

{
  "roleId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "displayName": "bi-reporting"
}

Reveal the password

POST /api/v1/databases/{id}/custom-roles/{roleId}/credentials
Authorization: Bearer <api-key>

Send no body. The role must be ready, without a pending change, and not expired. Each reveal is recorded in the account’s audit log.

200 OK

{
  "roleId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "profile": "custom",
  "displayName": "reporting",
  "accessProfile": "read_only",
  "username": "dbr_550e8400e29b41d4a716446655440000_c1",
  "ordinal": 1,
  "connectionLimit": 2,
  "generation": 1,
  "credentialGeneration": 1,
  "status": "ready",
  "host": "db.dbhost.app",
  "port": 6432,
  "database": "my-app",
  "tlsRequired": true,
  "password": "<password>"
}

Connect with TLS. Store the password in a secret manager and keep it out of logs and source control.

Rotate or revoke

POST /api/v1/databases/{id}/custom-roles/{roleId}/changes
Authorization: Bearer <api-key>
Idempotency-Key: <stable-unique-key>
Content-Type: application/json

{"kind":"rotate","confirmDisconnect":true}

The body must contain exactly kind (rotate or revoke) and confirmDisconnect: true. The Idempotency-Key header follows the same rules as on create.

Rotation and revocation close the role’s open connections. Open transactions on those connections roll back.

rotate sets a new password. revoke disables the login; the role keeps its slot until you delete it. The role must be ready, and a rotation also needs an unexpired credential. Changes are refused while a restore of the database is in progress or another credential change on the database is unfinished.

202 Accepted

{
  "operationId": "22222222-2222-4222-8222-222222222222",
  "roleId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "profile": "custom",
  "kind": "rotate",
  "status": "pending",
  "credentialGeneration": 2
}

The status code is 202 while status is pending and 200 when it is completed. credentialGeneration is the generation the change produces. Retry with the same key and body after an uncertain result; a different kind on the same key is refused.

Read a change

GET /api/v1/databases/{id}/custom-roles/{roleId}/changes/{operationId}
Authorization: Bearer <api-key>

Returns 200 with the same fields as above. It does not advance the change.

Reconcile a change

POST /api/v1/databases/{id}/custom-roles/{roleId}/changes/{operationId}
Authorization: Bearer <api-key>
Content-Type: application/json

{"confirmDisconnect":true}

The body must be exactly {"confirmDisconnect": true}. DBHost replays the recorded change and returns 202 while pending or 200 when completed. A change that has already completed is not applied again.

Delete a role

POST /api/v1/databases/{id}/custom-roles/{roleId}/delete
Authorization: Bearer <api-key>
Content-Type: application/json

{"confirm":true}

The body must be exactly {"confirm": true}. A ready role is revoked first, which closes its open connections, then removed from PostgreSQL. A revoked role is removed directly. Repeat the same call to continue a pending delete.

Status	Body	Meaning
200	`{"roleId": "...", "status": "removed"}`	The role is gone and its slot is free
202	`{"roleId": "...", "status": "pending", "phase": "revoke", "operationId": "..."}`	Revocation is still running
202	`{"roleId": "...", "status": "pending", "phase": "remove"}`	Removal is still running

DBHost does not cascade through your objects. If the role still owns objects or holds grants, the role stays revoked and the response lists what to clean up:

409 Conflict

{
  "error": {
    "code": "ROLE_DEPENDENCIES",
    "message": "Remove the listed customer grants or objects before retrying",
    "dependencies": [
      {
        "kind": "grant",
        "objectType": "table",
        "schema": "public",
        "name": "orders",
        "identity": "table public.orders"
      }
    ],
    "truncated": false
  }
}

kind is grant, owned_object, policy, other or other_database. At most 20 entries are returned; truncated: true means there are more. Revoke the grants or reassign the objects as the owner role, then call delete again.

Remove a revoked role

DELETE /api/v1/databases/{id}/custom-roles/{roleId}
Authorization: Bearer <api-key>

Send no body. This removes a role that is already revoked and returns 200 with {"roleId": "...", "status": "removed"}, or 202 with {"roleId": "...", "status": "pending"} while removal runs. Remaining dependencies return 409 ROLE_DEPENDENCIES without the list; use the /delete endpoint above to see it.

Reconcile an unfinished create

A create that was interrupted can leave a role in reserved. Retrying the original create with the same idempotency key and body is the simplest way to finish it. The two step endpoints are also available. Both take no body. POST /api/v1/databases/{id}/custom-roles/{roleId}/prepare creates the PostgreSQL role and returns 202:

202 Accepted

{
  "roleId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "profile": "custom",
  "username": "dbr_550e8400e29b41d4a716446655440000_c1",
  "displayName": "reporting",
  "accessProfile": "read_only",
  "ordinal": 1,
  "status": "sql_ready"
}

POST /api/v1/databases/{id}/custom-roles/{roleId}/admit applies the profile’s grants and opens the login. It returns 200 with the same fields and "status": "ready", or 409 CONNECT_GRANT_REQUIRED with grantSql as shown under Create a role. Neither step is needed after a successful create.

Errors

Status	Code	Description
400	`VALIDATION_ERROR`	Invalid ID, unexpected or missing body field, missing confirmation, or missing or invalid `Idempotency-Key`
400	`INVALID_JSON`	Request body is not valid JSON
401	`UNAUTHORIZED`	Missing or invalid API key
403	`PLAN_API_ACCESS_REQUIRED`	API access requires Pro or Business
404	`DATABASE_NOT_FOUND`	Database doesn’t exist, isn’t owned by this account or isn’t in the key’s scope
409	`MANAGED_ROLE_CONFLICT`	The role or database is not in a state that allows this action, or the idempotency key was used with a different request
409	`CONNECT_GRANT_REQUIRED`	The role needs `CONNECT`; run `grantSql` as the owner and retry
409	`CUSTOM_ROLE_REQUIRES_V3_CLONE`	The database is a clone from an older backup; create a new clone first
409	`ROLE_DEPENDENCIES`	The role still has grants or owns objects
413	`PAYLOAD_TOO_LARGE`	Request body is larger than the API limit
429	`RATE_LIMITED`	Too many requests; retry after the `Retry-After` header
503	`FEATURE_DISABLED`	Additional roles are temporarily unavailable
503	`MAINTENANCE`	DBHost is in a maintenance window; retry later
500	`INTERNAL_ERROR`	The request failed; retry the same request

Dashboard and CLI

The same actions are on the database detail page under Additional roles on every plan. The CLI provides them as dbhost managed custom-* commands; see CLI.

Overview

Databases

Backups

Collaboration

Webhooks

Previews

Operations

Additional roles API for managed databases

The role object

List roles

Create a role

Rename a role

Reveal the password

Rotate or revoke

Read a change

Reconcile a change

Delete a role

Remove a revoked role

Reconcile an unfinished create

Errors

Dashboard and CLI

​The role object

​List roles

​Create a role

​Rename a role

​Reveal the password

​Rotate or revoke

​Read a change

​Reconcile a change

​Delete a role

​Remove a revoked role

​Reconcile an unfinished create

​Errors

​Dashboard and CLI

The role object

List roles

Create a role

Rename a role

Reveal the password

Rotate or revoke

Read a change

Reconcile a change

Delete a role

Remove a revoked role

Reconcile an unfinished create

Errors

Dashboard and CLI