Start here

Authentication

Every request, REST or MCP, carries an organization API key in the Authorization header. The key decides the workspace, the scopes and the credit balance.

API keyScopedWorkspace-bound

The Authorization header

Keys start with ck_. Send one as a bearer token on every request; there are no cookies, signatures or OAuth flows on the documented surface.

Authorization

curl https://api.cuekoo.com/openapi/v1/tools \
  -H "Authorization: Bearer ck_live_xxxxxxxxxxxxxxxxxxxx"

The MCP endpoint uses the same header. MCP clients store it in their own configuration, so the snippet you paste into a client already contains the header and the server URL.

REST integrations use /openapi/v1/tools; MCP clients use /mcp. Both require an API key and use the same Tools and credit rules. Cookies and user ID tokens cannot authenticate these endpoints. The workspace's private /v1 business endpoints accept session cookies only and reject API keys, even when a session cookie is also present. Move existing API-key Tool calls from /v1/tools to/openapi/v1/tools; the arguments and results stay the same.

Scopes

A key carries a subset of the workspace's scopes. Tools check two of them:

Scope	What it allows
`tools.read`	Read-only Tools: channels, posts, creators, analysis, jobs and the credit balance.
`tools.write`	Tools that change workspace data, such as adding or replacing competitors.

Older keys may also carry org.read, monitor.read or monitor.write. No Tool requires these scopes, and they do not grant access to the workspace's private endpoints.

Choose a workspace

A key belongs to the organization, not to one browser session. Without a workspace header the request acts in the organization's default workspace. To address another workspace, send its id in X-Cuekoo-Workspace.

Explicit workspace

curl -X POST https://api.cuekoo.com/openapi/v1/tools/get_balance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Cuekoo-Workspace: 0190f3c2-7f1a-7c3e-9d21-6a0e5b8f2c11" \
  -H "Content-Type: application/json" \
  -d '{}'

Create, rotate and revoke keys

Keys are created in Settings → Developer. The plaintext key is returned once, at creation; the API stores only a hash. Create a second key before revoking the first if a deployment needs a clean rotation, then revoke the old one.

Revocation takes effect on the next request. A deleted key cannot be restored; create a new one instead.

What a failed check looks like

401 means the credential is missing, malformed, revoked or not an API key. The message asks for Authorization: Bearer ck_....
403 means the key is valid but the scope or workspace does not allow this action. The error code names the reason: forbidden_scope or forbidden_role.
402 means the workspace cannot pay for the call; see Credits.

The exact status and message for every error is in Errors.