Organizations

Every API key belongs to one organization, and by default every call acts there. To act in another organization, name it in the X-Company-Id header on every call:

curl https://connect.mindcloud.co/v2/workflows \
  -H "Authorization: Bearer $MINDCLOUD_API_KEY" \
  -H "X-Company-Id: K3vX9qLm2RtA"

Leave the header out and the call acts in the key's own organization. A call never falls back to the key's own organization when the header names one the key cannot reach: it is refused.

Which organizations a key can reach

A key acts as the person who created it, and it reaches:

Use this key across all of your organizations is a checkbox on the key, under API Keys in the app (isAllOrganizations in the API). With it, the key works in exactly the organizations its creator can open in the app right now: those they belong to with a role and, for MindCloud staff, the organizations their staff access opens. An organization that is restricted for MindCloud staff needs an approval first, as it does in the app. Keys with it show a globe in the API Keys list. Their creator sees them in every organization they open; the people who manage API keys in an organization see them, read-only, when the creator is a member there with a role. To check a key from the API, read it with Get API Key, using apiKey.id from Who Am I?. Without api_key:manage, List Companies tells you too: only a key with the setting lists organizations as member or staff.

In every organization, the key can do only what both allow: the permissions the key holds and the permissions its creator holds there right now. Remove the creator from an organization, change their role, or withdraw their approval, and the key changes with it on the next call. Only a key that has the setting can give it to a new key, so a key can never create one that reaches further than itself.

Find the organization

GET /v2/companies lists every organization the key can act in, with how it reaches each one (access: own, child, member, staff, staffLimited, or approvalRequired). Child organizations are listed only when the key and its creator hold child_company:access, and member organizations only where the creator's role grants permissions. A restricted organization approves MindCloud staff per part of MindCloud: staffLimited means the creator is approved for only some parts, which staffApprovedApps names (all when the organization is not restricted; set only on staff rows). Search it with q, which matches any part of the name, ignoring case, or the exact id:

curl "https://connect.mindcloud.co/v2/companies?q=acme&fields=id,name,access" \
  -H "Authorization: Bearer $MINDCLOUD_API_KEY"

Send the id you find in X-Company-Id. An organization marked approvalRequired is restricted: request access in the app before the key can act there. One marked staffLimited works on the endpoints of the parts of MindCloud listed in staffApprovedApps, and on endpoints both parts share (they accept either approval).

For agents: when you are asked to work in a named organization, find it with List Companies first and send its id in X-Company-Id on every call. If it is not in the list, stop and say so. Never fall back to the key's own organization.

Confirm where a call acted

• Every REST response names the organization it acted in, in its X-Company-Id response header. MCP tool results do not carry headers: the call acted in the companyId it named, or the key's own organization.
• GET /v2/me with the header answers that organization (company) and the permissions the key can use there (apiKey.effectivePermissions).

Endpoints that act in fewer organizations

Most endpoints accept X-Company-Id for every organization the key reaches. Each endpoint's reference lists the header and what it reaches.

• API keys, audit events, child organizations, link requests and leaving a parent act in another organization only as one of its members: with the setting on, in an organization the creator belongs to with a role. Neither a parent organization's key nor MindCloud staff access reaches them.
• Embedded end users (/v2/embedded/end-users/...) act only in the key's own organization: their data stays with the organization whose key manages them. Connections and runs that belong to an end user or installation are refused outside it too.

MCP clients cannot send headers, so the MCP tools take the organization as a companyId argument, under the same rule, except that companyId does not reach child organizations: use the REST API with X-Company-Id for those.

Audit

Every write a key makes in another organization is recorded in that organization's audit events, before it runs. The actor says how the key got there: parent_organization (a parent's key), member (the creator belongs there with a role and acts with it, with their user id) or mindcloud_admin (the creator acts with MindCloud staff permissions, even where they also hold a role).

Refusals

Standard endpoints answer these in error.details.reason. The endpoints that predate the v2 standard answer error.code (FORBIDDEN for an organization the key cannot reach).