Chelabase
ManagementRoles

Create a role

POST
/v1/databases/{id}/branches/{branch_id}/roles

Creates a role and answers with it. A LOGIN role (the default) gets a generated password; login: false makes a NOLOGIN role (a group) with none. owner_level gives it the owner's attributes (CREATEROLE, CREATEDB, BYPASSRLS, REPLICATION) and makes it a member of neon_superuser. inherit, connection_limit, valid_until, bypass_rls and member_of set the other allowed attributes and memberships; nothing else can be set. The password isn't in the answer: read it with the connection details and role. A role the compute couldn't take yet is pending and applied later.

Authorization

bearer
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Database id

Formatuuid
branch_id*string

Branch id

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

A role to create. Only the attributes listed here can be set; any other field is refused.

bypass_rls?boolean

BYPASSRLS: the role ignores row-level security. Default false.

connection_limit?integer

-1 (the default) is no limit.

Formatint32
inherit?boolean

INHERIT. Default true.

login?boolean

LOGIN, with a generated password. false makes a NOLOGIN role (a group) with no password. Default true.

member_of?array<string>

Roles to make it a member of. Each must exist and be the owner's to grant; never one of Chelabase's own (authenticator, anon, authenticated, neon_superuser, chelabase_…), the owner, a pg_… role, or the role itself.

name*string

^[a-z_][a-z0-9_]{0,62}$, and not a reserved name (postgres, anon, pg_…, …).

owner_level?boolean

Makes the role owner-level, like the branch owner: CREATEROLE, CREATEDB, BYPASSRLS and REPLICATION, and a member of neon_superuser. Default false.

valid_until?|

When the password stops working. Default: never.

Formatdate-time

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/databases/497f6eca-6276-4993-bfeb-53cbbbba6f08/branches/497f6eca-6276-4993-bfeb-53cbbbba6f08/roles" \  -H "Content-Type: application/json" \  -d '{    "name": "string"  }'
{  "blocked_keys": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "name": "string"    }  ],  "bypass_rls": true,  "connection_limit": 0,  "created_at": "2019-08-24T14:15:22Z",  "guard_exempt": true,  "inherit": true,  "level": "plain",  "login": true,  "member_admin": [    "string"  ],  "member_no_set": [    "string"  ],  "member_of": [    "string"  ],  "name": "string",  "origin": "owner",  "password": "generated",  "pending": true,  "valid_until": "2019-08-24T14:15:22Z"}

List a branch's roles GET

The branch's owner role first, then the others by name: roles made through the API and roles made in SQL, with their level, password state and the data API secret keys an owner-level role blocks. No passwords: read one with the connection details and `role`.

Change a role PATCH

Changes a role's LOGIN, owner level, attributes or memberships; fields left out stay as they are, and `valid_until: null` clears the expiry. Turning LOGIN on generates a password (read it with the connection details and `role`); turning it off drops the password. `member_of` replaces the list of the role's other memberships (`pg_*` and Chelabase's own groups stay). Works on roles made through the API, and on roles made in SQL that the owner administers; the owner can't be changed. A change starts from the role as SQL left it: SQL controls every role's attributes and memberships. Turning LOGIN on counts toward the branch's login-role cap. Answers with the role, never a password.