> ## Documentation Index
> Fetch the complete documentation index at: https://spillway.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Teams & orgs

> The tenancy hierarchy everything else is scoped against.

Every resource in Spillway — keys, budgets, guardrails, reports — is scoped under an
**org**, and usually further under a **team**. This hierarchy is enforced at the database
level with row-level security, not just checked in application code: an org can never read
another org's rows, full stop.

## Orgs

```jsonc theme={null}
// POST /api/orgs
{
  "name": "Acme Inc",
  "slug": "acme"
}
```

An admin-key request must carry the `X-Spillway-Org` header naming which org it's acting
on — an admin key isn't implicitly scoped to one org the way a session token is. (Admin-key
auth isn't enabled yet — see [API reference](https://spillway.mintlify.site/api-reference/introduction.md). Use a session
token for now.)

## Teams

```jsonc theme={null}
// POST /api/teams
{
  "name": "Checkout",
  "slug": "checkout"
}
```

Teams are how spend gets attributed for chargeback and how a budget scoped to `team` finds
its members. A virtual key's `teamId` (see [Virtual keys](https://spillway.mintlify.site/configuration/virtual-keys.md))
is what puts it under a team.

## Members

```jsonc theme={null}
// POST /api/members
{
  "userId": "<user-id>",
  "role": "admin"
}
```

Four roles: `owner`, `admin`, `member`, `viewer`. Roles gate control-plane actions (creating
budgets, approving requests, managing keys) — see [Approvals & automation](https://spillway.mintlify.site/configuration/approvals-and-automation.md)
for how roles feed into approval-chain `approvers`.

> [!WARNING]
>
> The last `owner` on an org can't be removed or demoted (`last_owner`) — there's always
> someone who can recover access.

## Where next

> **[Virtual keys](https://spillway.mintlify.site/configuration/virtual-keys.md)**
>
> Attribute a key to a team.

> **[Budgets](https://spillway.mintlify.site/configuration/budgets.md)**
>
> Scope a spend cap to an org, team, key, or provider.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.