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

# Organization API Keys

> Build an orchestrator — provision and configure agents programmatically with a scoped, container-bound machine credential

An **organization API key** (`reinx_org_live_…`) is how a backend or an orchestrator agent
manages a fleet: create agents, set their budgets, pause them, read their activity.

It is a **machine principal** — no human identity behind it — deliberately separated from the
agent keys that spend. An orchestrator provisions and supervises; the agents it creates do the
spending. Neither can do the other's job.

## Mint a key

**Settings → Organization → API Keys** in the dashboard. Minting requires step-up
re-verification, and you choose three things at that moment:

* **Scopes** — what kinds of action the key may take.
* **Binding** — which container (the organization, one project, or one team) it may act inside.
* **Daily create limit** — how many agents/projects/teams this key may create per UTC day.
  Defaults to 100; settable anywhere from 1 to 1,000. Lower it for a key that should only ever
  provision a handful of agents — it is the cheapest blast-radius control you have.

All three are fixed for the key's life, and **rotation preserves them**. Changing any means
minting a new key.

<Warning>
  The key is shown **once**. Store it in your backend's secret manager, never in source control and
  never in an LLM's prompt or memory. Revoke and re-mint if it leaks — revocation is immediate,
  because the key is verified against the database on every request with no cache.
</Warning>

## First call

```bash theme={null}
curl -H "Authorization: Bearer reinx_org_live_your_key_here" \
  https://api.reinx.ai/v1/agents
```

Returns the agents inside your key's binding. If you minted with only the default scopes, this
works and writes do not — see [scopes](/api-reference/authentication#organization-api-keys).

## Two ways to drive it

|          | REST                                          | MCP                                                          |
| -------- | --------------------------------------------- | ------------------------------------------------------------ |
| Endpoint | `api.reinx.ai/v1/*`                           | `mcp.reinx.ai/mcp`                                           |
| Best for | A backend service, a platform integration     | An LLM orchestrator agent                                    |
| Surface  | The management endpoints (see the note below) | The [management band](/mcp-tools/management-band) — 21 tools |

Same credential, same scopes, same binding, same contracts. Pick whichever fits how your
orchestrator is built; you can use both.

<Note>
  **Where the REST shapes are documented.** The agent endpoints have reference pages here
  ([Agents](/api-reference/agents), [Transactions](/api-reference/transactions)). The **project and
  team** management endpoints (`projects:write` / `teams:write`) do not have standalone reference
  pages yet — the MCP [management band](/mcp-tools/management-band) tools proxy them, so its
  request/response contracts (required `idempotencyKey`, the `version` loop, the full-replacement
  budget and approval-rules shapes) are the authoritative reference for the **management behavior**
  on both transports until the dedicated REST pages land. One caveat for **direct REST** callers:
  the MCP tool schemas are a deliberately **constrained subset** of the create fields — `POST
      /v1/projects` and `POST /v1/teams` also accept optional presentation fields (`color`, a tile
  `logo`) that the tools don't surface. A REST integration may send those; an MCP orchestrator
  creates with name + description only.
</Note>

<Warning>
  **The limits are not the same — size concurrency per transport.** MCP has its own, lower plan
  ceiling (60/600/3,000 per min for Free/Pro/Enterprise, versus 100/1,000/5,000 on REST), and
  management **writes** add 20/min per key and 40/min per org on top. An MCP management write then
  makes the proxied REST call, so it can also meet that route's own cap. Sizing an MCP workload from
  REST numbers will produce unexpected `429`s.
</Warning>

## Creating an agent

The one call with a contract worth reading before you write it:

```bash theme={null}
POST /v1/agents
Authorization: Bearer reinx_org_live_…
```

```json theme={null}
{
  "name": "Ad Spender",
  "teamId": "b2f1c7ce-…",
  "budgetCents": 50000,
  "idempotencyKey": "your-stable-uuid-here"
}
```

`idempotencyKey` is **required for machine callers** and must be generated and persisted by
*you*, before the call. The response carries the new agent's one-time API key, so a lost
response without a saved idempotency key means an orphaned agent and an unrecoverable
credential. With one, you simply replay the same key and payload and get the committed agent
back.

Full field list and error handling: [Agents](/api-reference/agents).

## Reconfiguring

All reconfiguring writes are optimistically concurrent: read to get the current `version`,
modify, write it back with that `version`, and on a stale token re-read and retry — never
blind-write.

<Warning>
  **A stale token does not return one code — it returns three, by endpoint.** Branch on all of
  them or you will miss conflicts on four of the five:

  | Endpoint                                      | Stale-version code         |
  | --------------------------------------------- | -------------------------- |
  | `PATCH /v1/agents/:id/budget-policy`          | `409 VERSION_CONFLICT`     |
  | `PUT /v1/{projects,teams}/:id/budget`         | `409 STALE_BUDGET`         |
  | `PUT /v1/{projects,teams}/:id/approval-rules` | `409 STALE_APPROVAL_RULES` |
</Warning>

**And the two write shapes are different:**

* **Agent budget policy** is a **partial** patch — an omitted field is left **unchanged**.
  Clear a spend ceiling by sending it explicitly as `null`.
* **Project and team budget** `PUT`s are **structured full replacements**: send `capCents`,
  the **complete** child array (`teams` for a project, `agents` for a team), and `version`.
  A missing child is rejected `422` — you cannot drop one to leave it alone. Clearing a cap
  means `capCents: null`, not omission.
* **Approval-rule** `PUT`s replace the whole `rules` array. Omitting an entry deletes that
  rule; there is no per-field merge.

Getting these backwards leaves a spending ceiling in force when you believed you removed it,
or silently drops a child allocation.

## What to read next

<CardGroup cols={2}>
  <Card title="Scopes and bindings" icon="shield" href="/api-reference/authentication#organization-api-keys">
    The six grantable scopes, the binding matrix, and why some reads need a write scope.
  </Card>

  <Card title="Limits and boundaries" icon="ban" href="/org-keys/deny-list">
    What an organization key can never do — and why your key got a 403.
  </Card>

  <Card title="Management band" icon="sliders" href="/mcp-tools/management-band">
    The 21 MCP tools, with the create and archive contracts in full.
  </Card>

  <Card title="Errors" icon="triangle-alert" href="/api-reference/errors">
    Every organization-key error code and what to do about it.
  </Card>
</CardGroup>