Authentication

Every request to the CRM Solid Public API must be authenticated with an API key sent as a bearer token. Each key is bound to a single workspace and carries a specific set of scopes that determine which operations it may perform. All responses are JSON.

API key format

A CRM Solid API key looks like this:

csk_<env>_<keyId><secret>

For example:

csk_live_a1b2c3d4e5f6abcdefghijklmnopqrstuvwxyz123456

• csk_ is a fixed prefix identifying the key as a CRM Solid key.
• <env> is the environment — live or test (see Environments).
• <keyId> is the public, non-secret identifier shown in the dashboard.
• <secret> is the secret portion, used to authenticate the request.

A key always maps to one workspace, and all actions performed with it are attributed to that workspace’s identity.

Caution

Keep your secret key safe. The full key (including the secret portion) is shown only once when it is created — store it securely and never commit it to source control or expose it in client-side code. If a key is lost or leaked, revoke it and mint a new one.

Sending an authenticated request

Pass your key in the Authorization header using the Bearer scheme:

Authorization: Bearer csk_live_…

The /v1/me endpoint returns the workspace identity associated with the key and requires no specific scope, so it makes a convenient connectivity smoke-test.

cURL

curl https://api.crmsolid.com/v1/me \
  -H "Authorization: Bearer csk_live_…"

JavaScript (fetch)

const res = await fetch('https://api.crmsolid.com/v1/me', {
  headers: {
    Authorization: 'Bearer csk_live_…',
  },
});
const data = await res.json();
console.log(data);

A successful response includes the workspace identity and the scopes attached to the calling key:

{
  "id": 42,
  "email": "[email protected]",
  "name": "Acme Inc.",
  "createdAt": "2024-01-15T09:00:00Z",
  "apiKey": {
    "keyId": "abc123def456",
    "scopes": ["contacts:read", "telegram:send"]
  }
}

Scope-based access

Access is scope-based: each key is issued with a specific set of scopes such as contacts:read or telegram:send. An operation that requires a scope your key was not granted returns 403 Forbidden. Grant a key only the scopes it needs.

Scope	Permission
telegram:send	Queue outbound Telegram messages
telegram:read	Read message status / delivery info
twitter:send	Send Twitter (X) DMs through connected accounts
contacts:read	Read contacts, conversation history, tags, lead score and activity timeline
contacts:write	Update contacts: notes, pipeline stage, tags, lead score, assignment
sequences:read	List campaign sequences and inspect their progress
sequences:write	Pause / resume sequences
analytics:read	Read dashboard KPIs and messaging stats
finance:read	Read finance summary, transactions, invoices and revenue sources
deals:read	List and read sales deals (pipeline)
deals:write	Create deals and move pipeline stages (won is panel-only)
tasks:read	List and read CRM tasks / reminders
tasks:write	Create tasks and change their status
email:read	Read email inbox threads and messages
email:write	Set email thread status and assignment
pipelines:read	Read pipeline boards and stage columns
webhooks:read	List webhook endpoints and their deliveries
webhooks:write	Register, rotate, test and delete webhook endpoints
agents:read	List and inspect AI agents
agents:run	Run the AI agent test playground (generates a draft reply, never sends)
jobs:read	Read the outbound message-job monitor
finance:write powerful	Create transactions and mark invoices paid (off by default)
email:send powerful	Send an email reply inside an existing thread (off by default)
keys:manage powerful	Mint, list and revoke API keys, attenuated to your own scopes (off by default)

Environments

Keys are environment-scoped via the <env> segment:

• csk_live_* — production keys that act on real workspace data.
• csk_test_* — keys for testing against the sandbox / test environment.

Use the environment that matches the data you intend to operate on.

Common authentication errors

Status	Meaning
401 Unauthorized	The bearer token is missing or invalid.
403 Forbidden	The token is valid but lacks the required scope, or the IP is not on the allowlist.

See Errors for the full list of status codes and the JSON error envelope.

Next steps

• Quickstart — make your first authenticated call.
• API reference — browse every endpoint and its required scopes.
• Errors — status codes, error slugs and the response envelope.