API

Go to Settings → Developers → API Keys to manage programmatic access to Cloodot — keys for custom integrations, scripts, or third-party tools that talk to your workspace.

API keys

Create a key

1. Click Create Key.
2. In the drawer, fill in:
   • Name — a friendly label (e.g. "Zapier integration" or "Internal reporting script").
   • Expiration — Never, 30 days, 90 days, or 1 year.
3. Click Create Key.

The full key value appears in a dialog with a Copy button.

Click Done once the key is stored securely.

Manage your keys

Existing keys appear in a table:

Delete a key

Click the trash icon on any key. You'll see a confirmation prompt:

"Any applications using this key will lose access immediately. This action cannot be undone."

Click Delete to confirm.

API documentation

The Developers page links to the full API Documentation, where you'll find:

• The complete REST API reference
• Authentication details
• Webhook setup and payloads
• Integration guides

Click the API Documentation card to open it in a new tab.

Authentication: API keys vs. OAuth

Cloodot's public API accepts two authentication methods with different permission models. Pick the one that matches what you're building.

API keys — full workspace access

API keys created on this page grant full read and write access to every resource in your workspace. They don't honor OAuth scopes — once a key is valid, it can call every endpoint the API exposes.

Use API keys when:

• You're building a server-side integration you fully control (internal scripts, your own backend, Zapier with stored credentials).
• The integration genuinely needs broad access across resources.
• A single team manages the key end to end.

OAuth tokens — scoped access

OAuth bearer tokens (issued through the OAuth 2.1 flow at /.well-known/oauth-authorization-server) are scope-gated. Each token carries a list of scopes — for example read:conversations, write:messages, read:contacts — and requests are rejected with 403 INSUFFICIENT_SCOPE if the scope is missing.

Use OAuth when:

• You're building a third-party app that other Cloodot customers will install.
• You want users to grant the smallest possible set of permissions (principle of least privilege).
• You're integrating with the MCP server — MCP access requires an OAuth token with the mcp:access scope and the relevant resource scopes per tool call.

Rate limiting

Limits are enforced per organization in fixed one-minute windows:

Response headers

Every response carries your current standing, so you can back off before you're throttled rather than after:

When you hit a limit

The API returns 429 Too Many Requests:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Please try again later."
  }
}

Wait the number of seconds given in Retry-After, then retry. Treat 429 as a signal to slow down, not as a failure to retry immediately — hammering a throttled window keeps it full. Use Logs to filter for 429 responses and find which integration is running hot.

Keep keys safe

• Never commit API keys to source control. Use environment variables or a secret manager.
• Scope by purpose. Create a separate key per integration so you can revoke one without breaking the others.
• Set an expiration date whenever you can — a strong safety net against lost or forgotten keys.
• Rotate keys regularly, especially after a teammate with access leaves your organization.
• Use Logs to spot unexpected activity on any key.

Related topics

• Developer Logs — monitor API usage and errors
• Integrations — connect Cloodot to other tools without writing code
• MCP Servers — extend Copilot with custom tools