Organisations, teams and roles

Not in the preview yet. This feature is built in the repository but is off in the v2.2.6 preview (test mode). Do not treat this page as available on a preview core. See ../preview.md and the release notes.

An organisation groups the people who spend from your budgets. It holds teams; each team holds budgets, each with an agent label (the name cost reports group by). People are members, vouched for by your identity provider, and each member holds roles at the organisation or at a team. A role only narrows what the deployment's owner can do: a member can never do something the owner token cannot.

These routes are on owner-api 1.8.0. On the hosted tier, pin Dynamo-Version: 1.8.0.

Status: organisations, teams, roles and cost reports are Live; single sign-on is Preview (off until a provider is configured, and tested against local mock providers only).

Roles

RoleWhat it allows, inside its organisation or team
viewerread budgets, streams, policies (and dry-run them) and cost reports; read a single approval, organisation or recourse case by id (not their lists)
approverread, and approve or reject approvals
funderread, and fund: open budgets for its team, open streams, meter, checkpoint, reserve (and confirm or release a reservation), open tasks and recourse cases
adminread, approve, control (freeze, thaw, stop, amend, revoke, close, resolve and escalate recourse) and govern (policies, teams, members, roles, budget assignments)

A viewer moves no money. An approver decides only approvals on budgets inside its scope. A role at the organisation covers every team in it; a role at a team covers that team only, so a team admin grants roles inside its team and nowhere else. Routes outside this list (the main switch, revenue settings, keys, webhooks and so on) stay with the owner token.

A member's refused request answers 403 role_forbidden, with the same body whether the object is outside its scope or does not exist.

Members and identity

A member is added as {issuer, subject}: the identity provider and the subject it vouches for. The core keeps only memberId = mbr_ followed by part of keccak256 over the issuer and subject; no record carries the raw subject. An identity is a member of one organisation per deployment.

Single sign-on

A self-hosted core signs members in with OIDC or SAML 2.0 when you configure a provider (CORE_SSO_OIDC, CORE_SSO_SAML; both off by default, https or loopback only):

RouteWhat it does
GET /sso/v1/oidc/startredirects to your provider (authorization code with PKCE)
GET /sso/v1/oidc/callbackverifies the id_token (issuer, audience, nonce, keys from your JWKS) and opens a member session
GET /sso/v1/saml/startredirects to your provider with a SAML authentication request (HTTP-Redirect binding, unsigned)
POST /sso/v1/saml/acsverifies the signed assertion against your provider's pinned key (RSA-SHA256), its issuer, audience, recipient and validity, and that it answers a request this core made, once
GET /sso/v1/sessionthe member's session and its CSRF token (the session id is replaced when it is due)
POST /sso/v1/logoutends the session (send the CSRF token)

On the hosted tier, the tenant owner sets the provider with PUT /tenant/v1/sso ({oidc?, saml?}, the same fields; each write replaces both, so a provider left out or sent as null is removed; GET /tenant/v1/sso shows it without the client secret), and members sign in at /sso/v1/t/<tenantId>/<test|live>/oidc/start (or /saml/start, with the ACS at /sso/v1/t/<tenantId>/<test|live>/saml/acs). A member session reaches that tenant's /owner/ routes in that environment only, never /tenant/ routes.

Only an identity that is a member with at least one role can sign in. The session is an HttpOnly, SameSite=Strict cookie; every write sends its CSRF token in X-Dynamo-CSRF; it carries the member's roles and nothing else.

Routes

RouteWhat it does
POST /owner/v1/orgs{orgId}: create an organisation (owner token only)
GET /owner/v1/orgsorganisations
GET /owner/v1/orgs/:idteams with their budgets, members with their roles
GET /owner/v1/orgs/:id/recordsthe organisation's signed records
POST /owner/v1/orgs/:id/teams{teamId}
POST /owner/v1/orgs/:id/members{issuer, subject}
POST /owner/v1/orgs/:id/roles`{memberId, scope: {kind: organisation \team, id}, role}`
POST /owner/v1/orgs/:id/roles/revokethe same body
POST /owner/v1/orgs/:id/budgets{budgetId, teamId, agent}: assign an existing budget to a team, once
POST /owner/v1/orgs/:id/teams/:team/budgets{budget, agent}: open a budget for the team (budget is the POST /owner/v1/budgets body) and assign it

Assigning a budget binds its team's and its organisation's policies to it. Organisation and team ids are 2 to 48 characters [a-z0-9-] and share one namespace.

Cost reports

GET /owner/v1/reports/costs?orgId=&teamId=&from=&to=&groupBy=&format= answers billed units and amounts from the signed meter records, grouped by org, team, agent, vendor (the stream's service node) and rail (the funding mode); groupBy is a comma list of those keys (default all), from and to are unix seconds (to exclusive), and format=csv answers the same rows as CSV. A report covers this deployment (one tenant) only and carries ids, units and amounts, never request bodies.

Who acted

Every organisation change is a record signed by the core, linked to the organisation's previous record, naming who acted. A budget's evidence export carries the chain of the organisation it is assigned to, and both offline verifiers check it. Freezes, thaws, stops, amendments, revocations and approval decisions made by a member name it too (member:<memberId>), as do policy and recourse records; actions taken with the owner token carry no actor field, as before.

On the hosted tier, the front door tells your tenant's core who acts on a dashboard or member session in a header it signs with a key held only by the front door and that core; the core refuses a request whose header is malformed, stale, replayed or signed with another key.