Authentication

The API authenticates requests with API keys. Every request sends the key in the X-API-Key header:

cURL
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

ScopeAllows
records:readRead records, timelines, tags, files and follow-ups
records:writeCreate, update and delete records, tags, notes, calls, files and follow-ups
records:exportExport records to a file, and a person's data for a GDPR request
records:eraseErase people by external id (GDPR erasure that can't be undone). Meant for sync integrations whose source system erases customers
imports:runImport records from files, and keep import mappings
events:writeSend events
segments:readRead segments and their members
segments:manageCreate, change and delete segments
analytics:readRead analytics

Messages and marketing

ScopeAllows
consent:writeRecord and withdraw marketing consent (email and SMS) without being able to send anything. Meant for sync integrations
emails:sendSend a single email to a person, and ask them for consent
sms:sendSend a single text message to a person
templates:manageManage email and SMS templates, images and saved sections
campaigns:manageCreate and change campaigns and read their results
campaigns:sendSend, schedule and resume campaigns
forms:manageManage sign-up forms, surveys and confirmation emails
automations:manageCreate, change, activate and pause automations
flows:runPut records into flows and work them through
flows:manageDesign flows: steps, buttons and activation

Setup

ScopeAllows
definitions:manageChange the data model (objects, fields, associations, event types) and install from the Market
webhooks:manageManage webhook endpoints and deliveries
integrations:manageIntegrations, website tracking and AI Insights access
channels:manageEmail and SMS settings: providers, senders, link domains, bounce limit, test mode and bot protection
settings:manageOrganisation settings, languages, contact pages and team messages

Organisation

ScopeAllows
team:manageInvite and remove people, change their roles, reset two-factor sign-in
apikeys:manageCreate and revoke API keys
billing:readRead invoices and usage
privacy:manageData 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.

RoleCan do
AdminEverything, including the team, billing, API keys and all settings
MarketerContacts, imports, segments, analytics, templates, forms, campaigns including sending, automations and flows
SellerContacts, notes, calls, follow-ups, flows, consent and one-to-one email. No mass sends, exports or settings
ViewerRead contacts, segments and analytics
DeveloperData 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

  1. Create a new key with the same scopes.
  2. Deploy it to your integration.
  3. 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.