Skip to Content
CallMitraDocs

Agencies & client workspaces

Use one agency API key to work in every client workspace with the X-Workspace-Id header.

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

  • 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

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

curl https://api.callmitra.ai/api/v1/campaigns/ \
  -H "X-API-Key: $AGENCY_API_KEY" \
  -H "X-Workspace-Id: 3f2b6c1e-8a4d-4f7e-9b2a-1c5d7e9f0a12"

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-IdResult
Not sent, empty, or the agency's own IDThe key works in the agency workspace.
A live client workspace of this agencyThe request runs inside that client workspace.
Anything else: another agency's client, an unrelated workspace, a deleted or detached client, not a UUID403 permission_denied, message This API key cannot work in that workspace.
A client workspace that is suspended409 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.

{
  "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

Client workspace IDs are UUIDs. List them with GET /api/v1/agency/clients:

curl https://api.callmitra.ai/api/v1/agency/clients \
  -H "X-API-Key: $CALLMITRA_API_KEY"
{
  "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). Otherwise you get 403 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.

To check a single client, call GET /api/v1/workspace with X-Workspace-Id. It returns that client's id and name.

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).
  • 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).

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 answers 403 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.

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.

On this page