# Agencies & client workspaces (/guides/agencies)

An agency runs CallMitra for several businesses. Each business gets its own **client workspace** under the agency, and the agency's integration reaches all of them with one API key.

## The model [#the-model]

- An **agency** workspace can own **client workspaces**. There is one level only: agency → client. A client workspace cannot have clients of its own.
- Each client workspace has its own leads, campaigns, agents, numbers, webhooks and usage. Data never mixes between clients, or between a client and the agency.
- Agency managers create, suspend, resume, detach and delete client workspaces in the console under **Settings → Workspaces**. These changes are console-only.
- Working inside a client workspace, in the console or through the API, opens an audited **acting session**. It is recorded in both the agency's and the client's audit logs.

## One key, many workspaces [#one-key-many-workspaces]

Create the key in the **agency** workspace ([Authentication](/authentication)). To act in a client workspace, send the client's workspace ID in the `X-Workspace-Id` header:

<Tabs groupId="language" persist items={["cURL","Node.js","Python"]}>
<Tab value="cURL">
```bash
curl https://api.callmitra.ai/api/v1/campaigns/ \
  -H "X-API-Key: $AGENCY_API_KEY" \
  -H "X-Workspace-Id: 3f2b6c1e-8a4d-4f7e-9b2a-1c5d7e9f0a12"
```
</Tab>

<Tab value="Node.js">
```js
const res = await fetch('https://api.callmitra.ai/api/v1/campaigns/', {
  headers: {
    'X-API-Key': process.env.CALLMITRA_AGENCY_KEY,
    'X-Workspace-Id': clientWorkspaceId,
  },
});
```
</Tab>

<Tab value="Python">
```python
res = requests.get(
    "https://api.callmitra.ai/api/v1/campaigns/",
    headers={
        "X-API-Key": os.environ["CALLMITRA_AGENCY_KEY"],
        "X-Workspace-Id": client_workspace_id,
    },
    timeout=30,
)
```
</Tab>
</Tabs>

The request then runs exactly as if it were made inside the client workspace: it reads and writes only that client's data, and anything it creates belongs to the client.

| `X-Workspace-Id` | Result |
| --- | --- |
| Not sent, empty, or the agency's own ID | The key works in the agency workspace. |
| A live client workspace of this agency | The request runs inside that client workspace. |
| Anything else: another agency's client, an unrelated workspace, a deleted or detached client, not a UUID | `403` [`permission_denied`](/errors/permission_denied), message `This API key cannot work in that workspace.` |
| A client workspace that is suspended | `409` [`conflict`](/errors/conflict), message `This client workspace is not active`. |

The API never answers `404` for a workspace it refuses, so a key cannot be used to discover which workspace IDs exist.

```json
{
  "detail": "This API key cannot work in that workspace.",
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "This API key cannot work in that workspace.",
    "param": null,
    "docUrl": "https://docs.callmitra.ai/errors/permission_denied",
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69"
  }
}
```

## Finding a client's workspace ID [#finding-a-clients-workspace-id]

Client workspace IDs are UUIDs. List them with [`GET /api/v1/agency/clients`](/api-reference/workspace/listAgencyClients):

```bash
curl https://api.callmitra.ai/api/v1/agency/clients \
  -H "X-API-Key: $CALLMITRA_API_KEY"
```

```json
{
  "success": true,
  "agency": { "id": "7b1c2f0e-1d2a-4c3b-9a8e-5f6d7c8b9a01", "name": "Acme Agency" },
  "clients": [
    {
      "id": "3f2e1d0c-9b8a-4765-8432-1f0e9d8c7b6a",
      "name": "Sunrise Dental",
      "status": "active",
      "createdAt": "2026-03-02T09:15:00+00:00"
    }
  ]
}
```

- `clients` holds every client workspace, oldest first. Send a client's `id` as `X-Workspace-Id`.
- `status` is `active`, `suspended` or `blocked`. Only `active` clients accept requests.
- The list has identity fields only. Spend, caps and allowance stay in the console (**Settings → Workspaces**).
- Any key of the agency can call it, whatever resources the key is limited to. A read-only key can call it too.
- The key must act as a workspace **manager** ([which user a key acts as](/authentication#keys-belong-to-the-workspace)). Otherwise you get `403` [`permission_denied`](/errors/permission_denied). A client workspace's key gets `permission_denied` too, because a client cannot have clients.
- The workspace must have the **agency add-on** (on its plan, or switched on for the workspace). Without it you get `403` [`permission_denied`](/errors/permission_denied).

To check a single client, call [`GET /api/v1/workspace`](/api-reference/workspace/getWorkspace) with `X-Workspace-Id`. It returns that client's `id` and `name`.

## Rules that still apply [#rules-that-still-apply]

- **The key's own limits travel with it.** A read-only key stays read-only inside every client, and a key limited to some resources is limited the same way in every client.
- **The rate limit is per key, not per workspace.** One agency key shares its 300 requests per minute across all clients. Give large clients their own key if they need their own budget ([Rate limits](/rate-limits)).
- **Webhooks are per workspace.** Each client workspace has its own webhook settings and receives events only for its own calls. Configure them while acting in that workspace.
- **Idempotency keys are per key**, so the same `Idempotency-Key` sent to two clients with the same key and path is treated as the same request. Include the client in your idempotency key ([Idempotency](/idempotency)).

## What an agency key cannot do [#what-an-agency-key-cannot-do]

- Create, edit, suspend, resume, detach or delete client workspaces, or open acting sessions for the console. Every `/agency` route except [`GET /api/v1/agency/clients`](/api-reference/workspace/listAgencyClients) answers `403` [`api_key_route_forbidden`](/errors/api_key_route_forbidden). That includes the agency usage report. Use the console for these.
- Create API keys, through the API or while acting in a client workspace in the console. Keys are always created in the agency's own workspace.
- Act in a workspace that is not one of its own live clients, or in a client of a client.
- Any endpoint that is not in the API reference, including the console-only routes listed in [Authentication](/authentication#which-endpoints-a-key-can-call).

## Audit trail [#audit-trail]

When an agency key first acts in a client workspace, CallMitra opens an acting session and writes an `agency.act.start` entry, marked as made through an API key, to the audit logs of **both** the agency and the client. The session is reused for that key and client for up to 8 hours (the default limit), so every request does not create a new entry. Changes made during the session are attributed to the key's user, acting for the agency.

## Related [#related]

- [Authentication & API keys](/authentication)
- [Errors](/errors)