AI access: developer documentation

What you get

• One HTTPS endpoint that speaks MCP (Streamable HTTP, JSON responses, stateless).
• Read-only by default. A new key can only look at data. Changing data needs a write permission that someone ticks on purpose when creating the key.
• Changes need a person's approval. A key with write permissions can create bookings, members, companies and draft invoices, and edit or cancel bookings. By default the AI cannot apply anything itself: its request waits in an approval queue inside Cowork until an owner or admin clicks Approve. See Making changes.
• Nothing can be deleted. There is no delete tool of any kind. Cancelling a booking only sets its status.
• Your organization only. A key is bound to the organization that created it. Nothing a client sends can select another organization.
• Least privilege. Each key carries permissions you choose. Tools a key is not allowed to use are not listed and cannot be called.

Quick start

1. An owner or admin opens Settings → AI access, clicks Create key, names it, ticks the permissions it needs and picks an expiry.
2. Copy the key immediately. It starts with cwk_ and is shown only once.
3. Point your client at the endpoint below and send the key as a bearer token.

Endpoint:       https://cowork.get200.africa/api/mcp
Authentication: Authorization: Bearer cwk_your_key_here

If the screen says API access is not enabled, ask your platform administrator to switch on "API access" for your organization.

Connect a client

Claude Code

claude mcp add --transport http cowork https://cowork.get200.africa/api/mcp --header "Authorization: Bearer $COWORK_API_KEY"

Claude on the web, Claude Desktop and mobile (claude.ai)

1. Open Customize → Connectors → Add custom connector (on Team and Enterprise plans an Owner adds it under Organization settings → Connectors).
2. Set MCP server URL to https://cowork.get200.africa/api/mcp and Authentication to No sign-in.
3. Under Request headers add the header name authorization with the value Bearer cwk_your_key_here (the word Bearer, a space, then the key). Alternatively use the header name x-api-key with just the key.
4. Click Add, then switch the connector on from the + → Connectors menu in a chat.

The Request headers section is a beta that only some Claude organizations have. If you don't see it, your account doesn't have access yet. Claude can't change a connector's headers after it's added: remove the connector and add it again.

Any MCP client that supports Streamable HTTP with custom headers

Add a remote server with the endpoint above and the header Authorization: Bearer <key> (an X-API-Key: <key> header also works). Client configuration formats differ, so follow your client's documentation for remote HTTP servers.

TypeScript (official SDK)

import { Client } from "@modelcontextprotocol/sdk/client/index.js"
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"

const transport = new StreamableHTTPClientTransport(new URL("https://cowork.get200.africa/api/mcp"), {
  requestInit: { headers: { Authorization: `Bearer ${process.env.COWORK_API_KEY}` } },
})
const client = new Client({ name: "my-app", version: "1.0.0" })
await client.connect(transport)

const { tools } = await client.listTools()
const result = await client.callTool({
  name: "list_bookings",
  arguments: { hasNotes: true, limit: 5 },
})
console.log(result.content)

Plain HTTP (curl)

curl -s https://cowork.get200.africa/api/mcp \
  -H "Authorization: Bearer $COWORK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The Content-Type and Accept headers are both required (without Accept the server answers 406). Every request is independent, so there is no session to open or close.

Permissions

Each key carries one or more permissions. Read permissions only look at data. Write permissions (marked below) additionally allow the AI to change data, always through the approval step, and each one needs the reading that goes with it.

Personal contact details are protected separately: without members:read, bookings and invoices show a person's name only, and searching by email is refused.

Making changes (the approval step)

Tools that change data (the ones marked changes data in the reference below) never change anything by being called. How a person approves depends on the key's approval mode, chosen when the key is created.

Approval in Cowork (default, recommended)

The call is checked exactly as the real change would be, then stored as a request in Settings → AI approvals. The AI is told it is waiting. An owner or admin sees what will happen and clicks Approve or Reject. Nothing the AI can send back will apply the change, so it is safe even if the AI client is set to "always allow".

{"name":"create_booking","arguments":{"spaceId":"...","memberEmail":"ann@example.com",
  "startTime":"2026-11-03T09:00:00+03:00","endTime":"2026-11-03T11:00:00+03:00"}}
// -> {"status":"pending_approval","changesMade":false,"requestId":"...","summary":"Create a hourly booking of ... Total KES 2,000.00 ..."}

// later, to see what happened
{"name":"check_change_request","arguments":{"requestId":"..."}}
// -> {"status":"APPROVED","changesMade":true,"result":{"bookingId":"..."}}   (or REJECTED with the reason, EXPIRED, FAILED)

• The change is checked again at the moment of approval. If the record, its price or the space's availability changed since the AI asked, it is refused and nothing is saved.
• The person who approves is recorded as the author of the change, and the key as the requester.
• Requests expire after 24 hours. A key can have at most 20 waiting, and make at most 60 requests per hour. Repeating an identical request returns the one already waiting.
• If the key is revoked or expires while a request is waiting, the request can no longer be approved.
• check_change_request only shows requests made by the same key.

Webhooks: get told instead of polling

When a key is created with a webhook URL, Cowork sends a signed POST to it as soon as a person approves or rejects one of that key's requests, or when approving it fails the final check. The AI platform no longer needs to call check_change_request in a loop. The URL must be a public https address on the standard port. The signing secret (whsec_…) is shown once, next to the key.

POST https://your-platform.example.com/hooks/cowork
Content-Type: application/json
X-Cowork-Event: change_request.approved      (or change_request.rejected, change_request.failed)
X-Cowork-Delivery: 5d0b…                      (unique per delivery attempt series)
X-Cowork-Signature: t=1767225600,v1=9a3f…

{"id":"evt_<requestId>","type":"change_request.approved","createdAt":"2026-11-03T09:14:02.000Z",
 "data":{"requestId":"...","tool":"create_booking","summary":"...","status":"APPROVED",
         "changesMade":true,"result":{"bookingId":"..."}}}

Verify every message before trusting it. The signature is an HMAC-SHA256, in hex, of the timestamp, a dot and the raw request body, using your secret:

import crypto from "crypto"

function verify(rawBody: string, header: string, secret: string) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")))
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false   // too old: possible replay
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex")
  return v1.length === expected.length && crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected))
}

• Answer with any 2xx status. Anything else, or no answer within 5 seconds, is retried (up to 3 tries in all, over about 5 seconds). The event id stays the same on retries, so treat it as idempotent.
• If every try fails, nothing is lost: the request keeps its outcome and check_change_request still returns it. The failure is shown in Settings → AI approvals.
• Events are sent for approved, rejected and failed requests. A request that simply expires sends nothing; check_change_request reports it as EXPIRED.
• Redirects are not followed, and addresses on private networks are refused.

Approval in the AI chat

Keys created with this mode work in two calls. The first call changes nothing and returns status: "needs_approval", a summary, the preview and a confirmationToken. The AI shows the summary to the person and, only if they explicitly say yes, calls the same tool again with the same arguments plus the confirmationToken. The result is status: "done".

• The token is signed, expires after 10 minutes, and is tied to the key, the tool and the exact arguments.
• If the arguments differ from the preview, or the record, its price or availability changed since, the change is refused.
• A key can make at most 30 changes per hour.

The limit of this mode: the server can prove a preview was requested and echoed back, not that a person read it. An AI client set to "always allow" can approve on the person's behalf. Prefer approval in Cowork.

In both modes

• It uses the same rules as the app: no double-booking, duration limits, the same pricing, and price changes flow onto invoices. It sends no emails.
• Invoices can only be created as drafts and only drafts can be edited. Sending, paying, voiding and changing amounts always stay with a person in the app.
• Changing a member's company, deleting anything, and changing email addresses are not possible through this API.
• Every applied change is written to Settings → Audit logs with what changed, and the key that asked for it (as mcp:cwk_…).
• Give write permissions only to keys held by people you trust.

Tool reference

List endpoints return at most 100 rows per call (default 25); page with offset. Dates are ISO 8601. Amounts are returned as strings to avoid rounding.

Errors and limits

Limits are per API key unless stated, and are enforced by the server.

Responses you may see:

Security and responsibility

• Treat a key like a password. Store it in an environment variable or a secrets manager. Never put it in source code, a shared chat or a browser. We store only a hash, so a lost key cannot be recovered: revoke it and create another.
• Give each tool its own key with only the permissions it needs, and choose an expiry. Revoke a key in Settings → AI access and it stops working immediately.
• Everything is logged. Each call is recorded in Settings → Audit logs (filter by "API key") with the key, the tool and the arguments used.
• Data leaves Cowork when you connect an AI. Anything the key can read is sent to whichever AI provider runs the assistant. You decide which providers to connect and which permissions to grant, and you are responsible for that choice, including any personal data of your members that you allow the key to read.
• Changes are opt-in, approved and limited. Keys read only unless a write permission was ticked. Writes need the approval step, can never delete anything, cannot send emails, take payments or finalize invoices, and are all logged. You are responsible for who holds a key that can change data.