v17

latestOpenAPI 3.0.1raw.githubusercontent.com2026-07-08165682.0 MB

Roles

Create role credentials

Authorization

A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:

Service Token Accesses create_production_branch_password, create_production_read_only_branch_password, create_branch_password

OAuth Scopes

Resource	Scopes
Organization	manage_passwords, manage_production_branch_passwords, manage_read_only_passwords, manage_production_read_only_passwords
Database	manage_passwords, manage_production_branch_passwords, manage_read_only_passwords, manage_production_read_only_passwords
Branch	manage_passwords, manage_read_only_passwords

post/organizations/{organization}/databases/{database}/branches/{branch}/roles

Path parameters

organizationstring required

Organization name slug from list_organizations. Example: acme.

databasestring required

Database name slug from list_databases. Example: app-db.

branchstring required

Branch name from list_branches. Example: main.

Request body

namestring

The name of the role

ttlinteger

Time to live in seconds

inherited_rolesstring[]

Roles to inherit from

with_replicationboolean

Whether the role should have the REPLICATION attribute

require_where_on_deletestring

Require WHERE clause on DELETE statements

require_where_on_updatestring

Require WHERE clause on UPDATE statements

Response

Returns the new credentials

idstring required

The ID of the role

namestring required

The name of the role

access_host_urlstring required

The database connection string

private_access_host_urlstring required

The database connection string for private connections

private_connection_service_namestring required

The service name to set up private connectivity

usernamestring required

The database user name

base_usernamestring required

The base username without branch routing suffix

passwordstring required

The plaintext password, available only after create

database_namestring required

The database name

created_atstring required

When the role was created

updated_atstring required

When the role was updated

deleted_atstring nullable required

When the role was deleted

expires_atstring nullable required

When the role expires

dropped_atstring nullable required

When the role was dropped

disabled_atstring nullable required

When the role was disabled

drop_failedstring required

Error message available when dropping the role fails

expiredboolean required

True if the credentials are expired

defaultboolean required

Whether the role is the default postgres user

ttlinteger required

Number of seconds before the credentials expire

inherited_rolesstring[] required

Database roles these credentials inherit

with_replicationboolean required

Whether the role has the REPLICATION attribute