Authentication
The API authenticates requests with API keys. Every request sends the key in the X-API-Key header:
curl https://crm.codefab.dev/api/v1/objects/contact/records \-H "X-API-Key: cfk_2Xw9…"
Requests without a valid key get 401 Unauthorized with the code INVALID_API_KEY.
Creating and managing keys
People whose role includes apikeys:manage create keys in the app under Settings → API keys:
- A key belongs to one organisation: everything it reads and writes is that organisation's data.
- The full key is shown once, at creation. Afterwards the app only shows a short fingerprint (
cfk_2Xw9aB1c…f3k0); the key itself is stored only as a hash. - A key can have an expiry date, and can be revoked at any time. Revoked or expired keys stop working immediately.
- A key can only get scopes the person creating it has. Asking for more is refused with
403(scope_not_yours).
Keep keys secret. Use them only from your servers, never in browser or mobile code, and never commit them to source control. If a key leaks, revoke it and create a new one.
Scopes
Each key carries the scopes it may use. Give an integration only what it needs; a request outside the key's scopes gets 403 Forbidden (forbidden). Every operation in the API reference lists its required scope, and GET /api/v1/access returns every scope with a short description.
Contacts and data
| Scope | Allows |
|---|---|
records:read | Read records, timelines, tags, files and follow-ups |
records:write | Create, update and delete records, tags, notes, calls, files and follow-ups |
records:export | Export records to a file, and a person's data for a GDPR request |
records:erase | Erase people by external id (GDPR erasure that can't be undone). Meant for sync integrations whose source system erases customers |
imports:run | Import records from files, and keep import mappings |
events:write | Send events |
segments:read | Read segments and their members |
segments:manage | Create, change and delete segments |
analytics:read | Read analytics |
Messages and marketing
| Scope | Allows |
|---|---|
consent:write | Record and withdraw marketing consent (email and SMS) without being able to send anything. Meant for sync integrations |
emails:send | Send a single email to a person, and ask them for consent |
sms:send | Send a single text message to a person |
templates:manage | Manage email and SMS templates, images and saved sections |
campaigns:manage | Create and change campaigns and read their results |
campaigns:send | Send, schedule and resume campaigns |
forms:manage | Manage sign-up forms, surveys and confirmation emails |
automations:manage | Create, change, activate and pause automations |
flows:run | Put records into flows and work them through |
flows:manage | Design flows: steps, buttons and activation |
Setup
| Scope | Allows |
|---|---|
definitions:manage | Change the data model (objects, fields, associations, event types) and install from the Market |
webhooks:manage | Manage webhook endpoints and deliveries |
integrations:manage | Integrations, website tracking and AI Insights access |
channels:manage | Email and SMS settings: providers, senders, link domains, bounce limit, test mode and bot protection |
settings:manage | Organisation settings, languages, contact pages and team messages |
Organisation
| Scope | Allows |
|---|---|
team:manage | Invite and remove people, change their roles, reset two-factor sign-in |
apikeys:manage | Create and revoke API keys |
billing:read | Read invoices and usage |
privacy:manage | Data retention, the audit log and erasing a person on request |
Roles and permissions
People in the app don't pick scopes one by one: each person has a role, and the role carries a set of scopes. An admin sets the role when inviting someone and can change it later under Settings → Team. The person is signed out, and their next sign-in has the new role's permissions.
| Role | Can do |
|---|---|
| Admin | Everything, including the team, billing, API keys and all settings |
| Marketer | Contacts, imports, segments, analytics, templates, forms, campaigns including sending, automations and flows |
| Seller | Contacts, notes, calls, follow-ups, flows, consent and one-to-one email. No mass sends, exports or settings |
| Viewer | Read contacts, segments and analytics |
| Developer | Data model, imports, events, webhooks, integrations and API keys. Sends nothing to customers |
GET /api/v1/access lists every role with its scopes. An organisation always keeps at least one admin, and nobody can change their own role.
Rotating a key
- Create a new key with the same scopes.
- Deploy it to your integration.
- Revoke the old key once traffic has moved over.
Keys record when they were last used, so you can confirm the old one has gone quiet before revoking it.