Authentication

Every request needs an API key in the Authorization header:

curl https://connect.mindcloud.co/v2/me \
  -H "Authorization: Bearer $MINDCLOUD_API_KEY"

A key belongs to one company, and every resource you read is scoped to that company automatically. There is nothing to configure per request.

Choose the smallest access level that fits the client:

• Read-only can read API data.
• Run workflows can read data and use workflow start and cancel endpoints.
• Full access can use every endpoint, including every write and API key management.

The MCP endpoint requires full access.

What a key acts as

Member and role writes need an acting user, because the rules protecting Owners compare who is asking against who is being changed. A key acts as the person who created it, with that person's authority and no more:

• It cannot change its creator's own role, or remove its creator from the company.
• It can change or remove an Owner only when its creator is an Owner or a MindCloud admin.
• It can invite a new Owner only when its creator is an Owner or a MindCloud admin.
• The last Owner cannot be demoted or removed, whoever asks.
• If the creator leaves the company, these writes stop working.

The last rule is the one that catches people out. A key that worked yesterday starts answering 403 MEMBER_ACTOR_NOT_RESOLVED the day its creator is removed, and the fix is to have a current member create a replacement key.

Verify a key

GET /v2/me describes the calling key and its effective scope:

{
  "success": true,
  "data": {
    "apiKey": { "id": "apikey_abc", "name": "Reporting", "companyId": "cmp_123", "accessLevel": "read_only" },
    "companyId": "cmp_123"
  }
}

Key handling

Keep keys on the server and out of client-side code. Keys can be managed entirely over the API: audit them with GET /v2/api-keys, mint new ones with POST /v2/api-keys, and shut one off with DELETE /v2/api-keys/:apiKeyId. A revoked key stops working immediately, and new key material is shown once, in the create response.