Developers

Connect a tool with an API key

Make a Chalk API key so Claude, Cursor, Zapier or your own code can work in your shop, choose what it can reach, and revoke it when done.

Updated By Adrian Gluchowski5 min read

On this page

An API key lets an outside tool use Chalk the same way the app does: look up a customer, add a lead, book a visit, send a quote. The owner or an admin makes keys under Settings > Connectors > Custom API, picks which parts of the shop each key can reach, and can revoke one at any moment. Keys come with the AI plan.

The full list of commands, with examples, is on the developer page. This page covers making and managing keys. To only send leads in from a website form or Zapier, the simpler Lead ingest connector may be all you need.

Make a key

  1. Open Settings > Connectors > Custom API. The same keys are under Settings > ChalkBot, in Developer API keys for Claude or Cursor.
  2. Press New key.
  3. Give it a Name you will recognise later, like "Zapier" or "Cursor on the shop laptop".
  4. Under What it can reach, set each area (below).
  5. Turn on Can message customers only if the tool needs to text or email customers.
  6. If you like, pick a lower role under Acts as, and a last day under Ends on.
  7. Press Create key.
  8. Copy the key from Copy this key now and keep it somewhere safe, like a password manager. Then press I have copied it. This is the only time Chalk shows it, because Chalk stores only a scrambled copy.

A new key starts able to read Clients, Sales and Schedule, and change nothing.

What a key can reach

Each area is None, Read or Write. Write includes read.

AreaWhat it covers
ClientsCustomers, properties, notes, tags
SalesRequests, quotes, the funnel, the price book
ScheduleJobs, visits, checklists, timers
InvoicesInvoices, payments written down by hand, expenses
Payments and moneyCard charges, refunds, saved cards, payouts, payroll, time cards
MessagesText threads, the inbox, notifications
FilesPhotos and documents
SettingsBusiness settings, history, saved views, and ChalkBot's settings, activity and chats (read only)
AutomationsAutomatic texts and emails, tag rules
TeamTeammates, roles, what each role can reach, sign-ins
ReportsThe Chalkboard, reports, the books, timesheets

Can message customers covers texts, emails, reminders, on my way and confirmations. Without it, the key cannot message anyone, even with write on an area. With it, the key also needs write on that area. STOP and the channels you have turned on always apply. Quiet hours apply to everything except a text sent straight from the Messages inbox (POST /api/messages/send), which goes at once like a reply you type.

Write on Team lets a key invite and remove teammates, change role permissions and reset sign-ins, but never touch an owner, an admin or the person who made the key. Write on Automations with Can message customers lets a key create, change and switch on automatic messages. Without it, the key can only pause every automation at once, or remove one.

Who the key acts as

A key acts as the person who made it, and can never do more than that person can do in the app today. If their role shrinks, so does the key.

Under Acts as you can pick a lower role instead, like office or sales, so the key gets that role's reach. Ends on is optional: after that day the key stops working and shows Expired. Leave it empty to keep the key until you revoke it.

Use the key

Send every call to https://app.chalkcrm.com plus the path, with the key in an Authorization header:

GET https://app.chalkcrm.com/api/users/me
Authorization: Bearer chk_live_xxxxxxxx

Every key starts with chk_live_. Send JSON with Content-Type: application/json. A call to /api/users/me is a safe first test: it tells you who the key acts as and what it can reach.

For every command, the permission it needs, error codes and safe retries, see the developer page. The machine-readable list is at www.chalkcrm.com/openapi.json. Point Claude, Cursor or a code generator at it.

Check, change or revoke a key

Your keys are listed with the start of the key, what they can reach, who made them and when they were last used.

  1. Press Manage on a key.
  2. Change its name, areas, role or end date and press Save. The secret stays the same.
  3. Check Last calls to see recent calls, with method, path, status and time.
  4. To stop it, press Revoke key, then Revoke. Anything using it stops at once.

Good to know

  • API keys come with the AI plan ($99 a month), and also work during the free trial. On Core a key cannot be made, and keys you already have stop working.
  • Only the owner or an admin can make, change or revoke keys, and only while signed in to the app. A key can never make or change keys, or open Settings > Connectors.
  • An admin cannot change a key that belongs to the owner.
  • Revoking cannot be undone. Make a new key instead.
  • Each key can make 240 calls a minute. Past that, Chalk answers 429 with a Retry-After header saying how many seconds to wait.
  • Last calls shows up to 20. Every change and every refusal is logged; plain reads only now and then. Calls older than 30 days are cleared.
  • Changes made with a key show in Settings > History as the person "via API key" and the key's name, so you can tell a script from a person.
  • Keys made before areas existed keep working exactly as they did. Open one with Manage, change an area and save to move it onto areas. A new name or end date alone leaves it as it was.
  • One key per tool. If one leaks or you stop using a tool, revoke just that key and nothing else breaks.