Skip to content

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:

response
{
"type": "https://databasezy.com/problems/forbidden",
"title": "Forbidden",
"status": 403,
"detail": "missing permission instances:write",
"required_permission": "instances:write"
}

How to fix it:

  1. Check what you hold. The portal hides actions you cannot take; from the CLI:

    shell
    zb api GET /v1/orgs/{org}/me/permissions
  2. 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.

  3. 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.

Under Members, fill in the Invite card with the email address and a role (Developer by default), then choose Send invite. From the CLI:

shell
zb members invite [email protected] --role developer
zb members invites # pending invites

You need members:manage, and you can only grant a role up to your own. The invite email contains a link valid for 7 days.

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:

shell
zb invites show # paste the link: organization, role, inviter, expiry
zb invites accept --use # paste the link, confirm, join and make it your default

The email address of the account you are signed in with must be the invited one and verified, as in the portal.

MessageCause 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_requiredThe organization requires two-factor authentication. Turn it on, then open the link again
402 seat_limitThe 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.

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.

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.