Roles and permissions

Tested with: Portal roles page · zb-auth permission matrix · Team and Enterprise plans

Access in Databasezy is decided by permissions. A role is a named set of permissions, and every person, service account and API key in an organization acts through one. You manage roles in the portal under Organization → Roles & permissions, and assign them under Organization → Members.

Organization roles

Each member has exactly one organization role:

Role	Who it is for
Owner	The person accountable for the organization. Has every permission and cannot be restricted.
Admin	Runs the organization day to day: databases, people, keys and billing.
Developer	Builds with databases and backups. Cannot delete databases or manage people.
Read-only	Looks at databases, backups and usage but changes nothing and never sees credentials.
Billing	Handles the plan, invoices and usage. Sees no databases.
Auditor	Reads the audit log and usage for compliance reviews.
Project access only	No organization-wide access. Works only in the projects you assign (see project roles).

In the API, Read-only is the role value viewer and Project access only is member.

Default permissions

Permission	Owner	Admin	Developer	Read-only	Billing	Auditor
`org:read` view the organization	✓	✓	✓	✓	✓	✓
`org:manage` organization settings	✓	✓
`org:delete` delete the organization	✓
`projects:read` view projects	✓	✓	✓	✓
`projects:write` create and rename projects	✓	✓	✓
`projects:delete` delete projects	✓	✓
`instances:read` view databases	✓	✓	✓	✓
`instances:write` create and change databases	✓	✓	✓
`instances:delete` delete databases	✓	✓
`credentials:reveal` reveal connection credentials	✓	✓	✓
`backups:read` view backups	✓	✓	✓	✓
`backups:write` take and schedule backups	✓	✓	✓
`backups:restore` restore backups	✓	✓	✓
`members:manage` manage members and roles	✓	✓
`apikeys:manage` manage API keys	✓	✓
`billing:read` view billing	✓	✓			✓
`billing:manage` manage billing	✓	✓			✓
`usage:read` view usage	✓	✓	✓	✓	✓	✓
`audit:read` view the audit log	✓	✓				✓
`support:grant` grant support access	✓	✓

A blank cell means the role does not have the permission. Project access only starts from org:read alone.

Adjusting the predefined roles

On the Team and Enterprise plans you can change what Admin, Developer, Read-only, Billing and Auditor allow for your organization. On other plans the Roles & permissions page shows the same matrix without editing.

The rules:

The owner is fixed. The Owner role always has every permission and cannot be edited.
Some permissions are locked. org:read is always on for every role; org:delete belongs to the owner only.
You can only grant what you hold. To add a permission to a role you need that permission yourself, plus members:manage.
You cannot lock yourself out. A change that would take members:manage away from your own role is refused.
Reset to default puts a role back to the matrix above in one step.
Every change is recorded. Edits and resets appear in the audit log with who made them, and are emitted as security events, so they reach your SIEM if you stream the audit log.
Changes apply everywhere at once, including to API keys. An API key acts with the intersection of its owner’s role and the key’s scopes, so narrowing a role also narrows every key its members created.

# Let Developers delete databases in this organization
curl -X PATCH https://api.databasezy.com/v1/orgs/$ORG/predefined-roles/developer \
  -H "Authorization: Bearer $ZB_TOKEN" -H "Content-Type: application/json" \
  -d '{"permissions": ["org:read","projects:read","projects:write","instances:read","instances:write","instances:delete","credentials:reveal","backups:read","backups:write","backups:restore","usage:read"]}'

# Undo it
curl -X POST https://api.databasezy.com/v1/orgs/$ORG/predefined-roles/developer/actions/reset \
  -H "Authorization: Bearer $ZB_TOKEN"

Project roles

Project roles give someone access to particular projects instead of the whole organization, for example a contractor who should only touch staging. They are available on the Team and Enterprise plans.

On Members, set the person’s role to Project access.
Pick one or more projects and a role for each: Admin, Developer or Read-only.

A project role carries the database, credential, backup and usage permissions of the organization role with the same name (including your customizations), limited to that project: projects:read, projects:write, instances:*, credentials:reveal, backups:* and usage:read.

People whose access comes only from project roles see only those projects in the portal, CLI and API. A project role never includes deleting the project, billing, members, API keys or organization settings, even at Admin.

curl -X PUT https://api.databasezy.com/v1/orgs/$ORG/projects/$PROJECT/members/$USER \
  -H "Authorization: Bearer $ZB_TOKEN" -H "Content-Type: application/json" \
  -d '{"role": "developer"}'

Two-factor authentication

Two-factor authentication (an authenticator app, with recovery codes as a backup) is optional and recommended. Turn it on under Account → Security.

Once you turn it on, it is always enforced: every sign-in asks for your second factor before the portal, the CLI or the API accept the session.
Organizations can require it: every member of an Enterprise organization, or of an organization that signed the BAA, must use two-factor authentication. Sessions without it are refused for that organization.
Sensitive actions (revealing credentials, writable SQL consoles, logs, network changes, erasure, closing the organization, role changes, signing the BAA, SSO and SIEM settings) work without a second factor only when you have not turned it on and the organization does not require it. They are recorded in the audit log either way.
API keys are not affected; protect them with scopes, expiry and IP allow-lists.

Custom roles

On Enterprise, you can also create custom roles: named permission sets assigned on top of an organization role, such as a DBA on-call rotation that may restore backups. The same rule applies: a custom role can only contain permissions its creator holds. Team roles (lead, developer, operator, viewer) are described in Teams and approvals.