Skip to main content
An organization is the tenant a sandbox, preview, or other resource belongs to. This guide covers understanding personal vs. named organizations, why administering one happens on the dashboard rather than through your API key, and — the part you’ll actually script against — how to select and use an organization you already belong to from the CLI, an SDK, or raw REST. See Organizations for the full concept and field reference.

​
Personal vs. named organizations

Every account has an implicit personal organization — the tenant an omitted org context resolves to. It always has exactly one member (you, as owner), and it can’t be invited into. A named organization is created explicitly and can have multiple members with different roles (owner or member — a closed set, no custom roles).
Your personal organization is always available and needs no setup. Everything in this guide about using an organization applies to it too — omitting org context entirely is equivalent to explicitly selecting your personal organization.

​
Administration is dashboard-only

Creating, renaming, and reading organizations; listing, changing the role of, or removing members; and inviting people all require a Supabase session JWT. A personal API key (byk_) is rejected outright on every one of these operations, even one belonging to the organization’s own owner.
This is a deliberate split, not a gap: these are dashboard-facing operations where a signed-in browser session is doing the asking, not an automated client. If you’re setting up a team — creating the organization, inviting members, changing roles — that all happens by signing into the Bonya dashboard, not by scripting it with an API key. See Organizations for why the split exists and exactly which operations it covers. What an API key can do is select which organization its calls run against, once you’re already a member of one. That’s the rest of this guide.

​
Using an organization from the CLI

bonya org controls which organization your commands act in by default, so you don’t have to pass --organization-id on every command:
bonya org list prints a table of organizations you belong to, marking the current one. bonya org use <name-or-id> saves an organization as the default for future commands — omit the argument to pick from an interactive list. The value saved to disk is always resolved to an id, never a name, since a name can be renamed out from under a saved selection but an id can’t.
bonya org show reports what’s currently in effect and where it came from (flag, environment variable, or saved selection) — useful when you’re not sure which org a command is about to hit. bonya org clear removes the saved selection and falls back to your personal organization.
A saved org use selection wins only while you’re still a member of that organization. If you’re removed, commands silently fall back to your personal organization rather than erroring.

​
Using an organization from the SDKs

Every SDK reads BONYA_ORGANIZATION_ID from the environment as the default org context for every call, or accepts an explicit override at client construction:
For the Go SDK specifically, an explicitly empty WithOrganizationID("") (or BONYA_ORGANIZATION_ID="") makes NewClient return an error rather than silently falling back to your personal organization — this catches CI jobs that would otherwise run against the wrong tenant when a variable expansion comes back empty.

​
Using an organization from raw REST

Sandbox-scoped calls (sandboxes, exec, sessions, files, previews) accept an optional header to select org context:
  • Omitted — resolves to your personal organization.
  • Malformed — 400.
  • Well-formed but you’re not a member — 404, not 403 (the API doesn’t confirm an organization exists to a non-member).
This header has no effect on the JWT-only organization-administration endpoints described above — it’s for scoping API-key calls to sandboxes, previews, and the like, not for managing the organization itself.

Organizations

Authentication

org CLI reference