Help
Invites, roles and "missing permission" errors
Tested with:Databasezy API v1 · zb CLI 0.1
Everything a person or API key can do in Databasezy is decided by permissions, grouped into roles. When an action
is refused with 403 and a required_permission, the person or key does not hold that permission in this
organization. An owner or admin can give it by changing the role. The full permission matrix is on
Roles and permissions; team roles and approvals are on
Teams and approvals.
403 forbidden: “missing permission instances:write”
Section titled “403 forbidden: “missing permission instances:write””The problem body names the permission that was missing:
{ "type": "https://databasezy.com/problems/forbidden", "title": "Forbidden", "status": 403, "detail": "missing permission instances:write", "required_permission": "instances:write"}How to fix it:
-
Check what you hold. The portal hides actions you cannot take; from the CLI:
shell zb api GET /v1/orgs/{org}/me/permissions -
Ask an owner or admin to change your role under Members, or, on Team and Enterprise, to add the permission to your role under Roles & permissions.
-
If the call came from an API key, the key acts with its role narrowed by its scopes. Create a new key with the right role or scopes (API keys).
Common cases: Developers cannot delete databases (instances:delete) or manage members (members:manage); Read-only
never sees credentials (credentials:reveal); Billing sees no databases; only owners have org:delete.
A 403 with another type is not a role problem: mfa_required and reauth_required ask you to sign in again
(two-factor authentication), and sso_required asks you to sign in through your identity
provider (SSO and SCIM).
I cannot see a project or database that exists
Section titled “I cannot see a project or database that exists”If your role is Project access only (member), you see only the projects you were assigned. Ask an admin to
assign the project to you, or to change your organization role. Also check that the portal, or the CLI with
zb orgs use, is pointed at the right organization: resources in another organization are never shown.
How do I invite someone?
Section titled “How do I invite someone?”Under Members, fill in the Invite card with the email address and a role (Developer by default), then choose Send invite. From the CLI:
zb members invites # pending invitesYou need members:manage, and you can only grant a role up to your own. The invite email contains a link valid for 7
days.
How do I accept an invite from the CLI?
Section titled “How do I accept an invite from the CLI?”Open the link from the email in the portal, or accept it from the CLI while signed in with your own session (an API key acts for an organization, not a person, and cannot accept). Run the command without the link and paste it at the prompt, which hides what you type; the link is a credential, so do not type it as an argument where your shell history keeps it:
zb invites show # paste the link: organization, role, inviter, expiryzb invites accept --use # paste the link, confirm, join and make it your defaultThe email address of the account you are signed in with must be the invited one and verified, as in the portal.
The invite link does not work
Section titled “The invite link does not work”| Message | Cause and fix |
|---|---|
| “invite is no longer valid” | The invite expired (7 days), was revoked or was already used. Ask for a new invite |
| “this invite was sent to a different email address” | Sign in with the account whose email received the invite, or ask for an invite to your address |
| “you are already a member of this organization” | Nothing to do; switch to the organization in the portal |
403 mfa_required | The organization requires two-factor authentication. Turn it on, then open the link again |
402 seat_limit | The organization is on Free or Solo, which include one member. An owner upgrades to Team or frees a seat |
Pending invites count as seats. Auditors do not use a seat.
How do I change someone’s role or remove them?
Section titled “How do I change someone’s role or remove them?”Under Members, change the role or remove the person, or use zb members set-role <USER> <ROLE> and
zb members remove <USER>. Role values in the API and CLI are owner, admin, developer, viewer (Read-only),
billing, auditor and member (Project access only).
- A new role may not exceed your own.
- Only owners can change or remove owners.
- The last owner cannot be demoted or removed. To hand over an organization, make the new person an owner first.
- Removing a member does not revoke API keys they created. Review API keys and revoke theirs.
402 plan_limit when editing roles
Section titled “402 plan_limit when editing roles”Editing the predefined roles and assigning project roles are available on Team and Enterprise. Custom roles are Enterprise only. On other plans the Roles & permissions page shows the matrix without editing.
Still stuck?
Section titled “Still stuck?”Search the help center or ask the assistant in the portal Help panel. If that does not solve it, open a support
ticket from the portal (Help → Open a ticket, category account) and include the full error with its
required_permission, the x-request-id response header, whether you used the portal, the CLI or an API key, and
the time in UTC. Never paste passwords, connection strings with passwords, API keys or patient data (PHI) into a
ticket. See How to get help.