Concepts¶

Understanding how b'nerd organizes identity and resources will make everything else click into place.

Accounts¶

An account represents a person. It has a login (email address), a display name, and can belong to one or more organizations through memberships. You authenticate as an account — all API tokens and JWT sessions are tied to an account.

GET /accounts/me returns your account together with:

memberships[] — every membership the caller holds (one entry per organization the account belongs to), each carrying the membership id, organization_id, role, and permissions.
current_organization_id — the organization resolved for the current request (see Organization context below).

Organizations¶

An organization is the top-level billing and access boundary. Every resource on the platform belongs to an organization. When you sign up you create both an account and a first organization at the same time.

Organization creation is not a self-service API call

There is no public POST /organizations endpoint. Organizations are created through the signup flow or by b'nerd staff via the admin interface. To add an existing account to a second organization, use invitations (see below).

Key properties:

Has one or more members (accounts with a role and permissions)
Has at least one account with the Admin role at all times — the platform will refuse an action that would remove the last admin
Is the scope for static API tokens — a token is valid within the organization it was created for
Is the billing entity: invoices, subscriptions, and payment methods are per organization

Organization context¶

When an account is a member of more than one organization, every API request must declare which organization it targets. The server reads ?organization_id=<uuid> from the query string and validates that the caller is actually a member of that organization. Requests that name an organization the caller does not belong to are rejected with 403 Forbidden (fail-closed — there is no server-side default for multi-org accounts).

curl "https://api.bnerd.cloud/projects?organization_id=$ORG_ID" \
  -H "Authorization: Bearer $TOKEN"

The resolved organization_id is echoed back in every response envelope's metadata and in current_organization_id on GET /accounts/me — the dashboard uses this to confirm a switch landed.

Accounts that belong to only one organization continue to work without the parameter; the server resolves the single membership automatically.

Projects¶

A project groups resources within an organization. Projects are a lightweight namespace: DNS zones, Kubernetes clusters, compute resources, and object storage users are created inside a project.

Projects exist mainly to separate environments (e.g. production, staging) or workloads within a single organization. They do not create separate billing boundaries — all projects within an organization share its quota and billing.

Memberships¶

A membership links an account to an organization and carries that account's role and permissions within that organization.

Role — either Admin or Member. Admins bypass all per-category permission checks. Members are restricted to the permissions explicitly listed on their membership.
Permissions — a set of allowed actions (read, create, update, delete) across eight resource categories: projects, openstack, garden, rgw, apps, billing, members, settings.

See Roles & RBAC for the full permission model and built-in presets.

Invitations¶

You add new members to an organization by sending an invitation to their email address. Invitations carry a role and permissions and expire if not accepted. Invitation lookup and accept/decline are the only unauthenticated API endpoints.

An existing account can also be invited into a second (or third, …) organization. When the account holder accepts that invitation they gain an additional membership. From that point on, all their API requests must carry ?organization_id=<uuid> to declare which organization to act in (see Organization context).

Summary¶

Account
  ├── Membership ──► Organization A
  │                       └── Project
  │                             └── Resources (servers, DNS zones, clusters, …)
  └── Membership ──► Organization B
                          └── Project
                                └── Resources

One account can be a member of multiple organizations, each with different roles and permissions. Permissions are evaluated per-membership — the same account can be an Admin in one organization and a read-only viewer in another.