FAQ

Quick answers to the questions we hear most. If you’re just getting started, the Quickstart walks you through your first request end to end.

How do I get an API key?

API keys are created from inside the CRM Solid app at app.crmsolid.com. Open your workspace settings, find the API keys section, and create a new key. You choose the scopes the key is allowed to use at creation time, and the secret is shown only once — copy it somewhere safe.

See Authentication for the full walkthrough.

What does a key look like, and where do I put it?

Keys use the format csk_<env>_<keyId><secret> — for example csk_live_abc123def456.... The <env> segment tells you which environment the key belongs to (e.g. live), so you can tell production keys apart at a glance.

Send the key as a bearer token on every request:

Authorization: Bearer csk_live_abc123def456...

What are scopes?

Each key is issued with a specific set of scopes that limit what it can do — for example contacts:read or telegram:send. A request that needs a scope your key wasn’t granted returns 403 Forbidden. This lets you create narrowly-permissioned keys (e.g. a read-only key for reporting) rather than handing out full access.

Is there a quick way to test that my key works?

Yes. Call GET /v1/me with your key — it returns your workspace identity and the scopes attached to the key. No specific scope is required, so any valid key can call it, which makes it a good connectivity smoke-test. See the API reference for details.

What are the rate limits?

Rate limits are applied per key. Every response includes these headers so you can pace your requests:

X-RateLimit-Limit — the maximum number of requests allowed in the current window.
X-RateLimit-Remaining — how many requests you have left.
X-RateLimit-Reset — when the window resets.

Read these headers and back off before you hit zero. When you do exceed the limit, you’ll get an error response — see Errors for how to handle it.

Why am I getting a 401?

A 401 Unauthorized means the key wasn’t accepted — usually a missing, malformed, or revoked key, or a missing Authorization header. Double-check that you’re sending Authorization: Bearer <key> and that the key hasn’t been rotated. More detail in Errors.

Why am I getting a 403?

A 403 Forbidden means your key is valid but doesn’t have the scope required for that operation. Check the scopes on the key (call GET /v1/me) and, if needed, create a new key with the additional scope. See Authentication.

Is there an MCP server for AI agents?

Yes. An MCP (Model Context Protocol) server is available at the same host: POST /mcp on https://api.crmsolid.com. It lets AI agents work with your CRM data through the same scope-based permissions as the REST API. See the MCP integration guide.

Can I use this with Claude or Cursor?

Yes — any MCP-compatible client (such as Claude or Cursor) can connect to the POST /mcp endpoint using your API key. The MCP integration guide covers how to configure it.

Is finance data read-only?

Yes. The Finance endpoints are read-only — you can fetch the finance summary, transactions, invoices, and revenue sources, but the API does not create or modify finance records. Note too that moving a deal to “won” (which books revenue) is panel-only and is not done through the API.

How do I get notified when things change?

Use webhooks to receive events instead of polling. See the Webhooks guide to set up endpoints and handle delivered events.

Is there a sandbox or test environment?

Keys are environment-tagged via the csk_<env>_ prefix, so you can keep test and production credentials clearly separated. For safe experimentation, create a key with the lowest scopes you need (for example, a read-only contacts:read key) and test against it before granting broader, write-capable scopes like telegram:send.