Skip to content
Cobre

Organizations and workspaces

Two containers, one inside the other, and almost everything in Cobre is scoped to the inner one.

Organization

Section titled “Organization”

An organization is the top-level tenant: a company, a customer, a business unit. It owns workspaces, and it is the boundary that billing and membership are anchored to.

You rarely act on an organization. Its role is to be the thing workspaces belong to.

Workspace

Section titled “Workspace”

A workspace belongs to an organization and is the unit almost everything else is scoped to — agents, runs, sessions, skills, knowledge bases, service keys, schedules, budgets. Two workspaces in the same organization share nothing by default.

This is the single most useful thing to internalise about the model: when you wonder “who can see this row”, the answer is almost always “the workspace it was created in”.

Cross-tenant isolation is enforced rather than filtered. A resource that belongs to another tenant answers 404, not 403 — a 403 would confirm that the identifier exists.

Roles

Section titled “Roles”

Membership carries one of five roles, in increasing order:

RoleWhat it means in practice
viewerRead. Can see runs, agents and their output; cannot start anything.
memberEverything a viewer can do, plus submitting, cancelling and resuming runs.
adminConfiguration: agents, tools, schedules, members, keys.
ownerThe organization’s own settings, and everything below.
operatorPlatform staff. Not a tenant role — it is the person running the deployment.

Two things follow that surprise people:

A role floor is a minimum, not a grant. Every endpoint declares the lowest role that may call it at all. Clearing that floor gets you past the door; what rows you then see is decided separately, by scope. A member floor means a viewer is refused — it does not mean every member sees every row.

operator is not “super admin for your organization”. It is the deployment’s own staff role, and the operations behind it are excluded from this documentation entirely. They are in the OpenAPI document your deployment serves.

Users, service keys and delegation

Section titled “Users, service keys and delegation”

Three kinds of caller, and they authenticate differently:

  • A user signs in and gets an access token, rotated by refresh. This is what a person’s session carries.
  • A service key is a long-lived credential for a backend. It is created once and its plaintext is shown once and never again; rotating it issues a new plaintext and retires the old hash immediately.
  • Delegation lets an admin or above act as another user for one request, via the X-Acting-User header.

The same “shown exactly once” rule applies to an invitation link, and to a webhook endpoint’s signing secret.

Secrets

Section titled “Secrets”

A workspace holds named secrets that tools and agents resolve at run time. Secret values are write-only: the list endpoint returns names and metadata and never values. There is no screen and no endpoint that reads a secret back — if you have lost it, you rotate it.

Budgets

Section titled “Budgets”

A budget is a ceiling on spend, keyed on (workspace, period). A workspace may hold a daily and a monthly ceiling, and both are checked.

When a budget is exhausted, a submission is refused with 402 before the run row is inserted. A blocked submission therefore leaves no artifact — there is no failed run to find afterwards, because no run was ever created. This is deliberate, and it is why a 402 should be treated as terminal until an operator raises the limit rather than retried.

period_start is an anchor, not a frozen window: the current period rolls forward from it, and a 31st anchor clamps to the last day of a shorter month rather than spilling into the next one.

Where to next

Section titled “Where to next”