
Every request you send to the AiEngage CRM REST API has to prove who is calling. The API does this with Bearer token authentication: you put a secret token in the Authorization header of each request, and the CRM checks it before it returns or changes any data.
This guide explains how that works in plain language, then walks you through it step by step:
Open the API Keys page and understand what is on it.
Create a Personal Access Token (the Bearer token) with the right scopes and expiry.
Copy the token safely — it is shown only once.
Send the token in the Authorization: Bearer header (with ready-to-copy examples).
Test the token in the interactive API reference and read the response.
Fix the most common authentication errors (401, 403 and 429).
Revoke a token you no longer need, or one that may have leaked.
Each screenshot has a red ring and arrow on the part to look at, followed by a description of the whole screen so you can match it against your own. The token shown in this guide is an example, not a real key, and other keys’ prefixes are blurred.
You need access to Settings → Developer Hub → API Keys. If you can’t see it, ask your CRM administrator.
Your plan must include API access. If it doesn’t, every call returns 403 with the category NO_API_ACCESS and the message “API access is not included in your current plan”.
A tool that can send HTTP requests — for example a terminal with curl, Postman, your own code, or an automation tool such as Zapier or Make. You can also test straight from the API reference page in your browser (Step 6).
Think of a Bearer token like a hotel key card: whoever bears (holds) the card can open the door, so you keep it safe and cancel it if it is lost. In practice:
You create a token in the CRM. It looks like cak_live_ followed by a long random string.
Your app adds one line to every request: Authorization: Bearer cak_live_….
The CRM looks the token up, checks it is active, not expired, allowed from your IP address, and that its creator is still an active user.
It then checks the token has the scope the endpoint needs (for example crm.contacts.read) and that you are within your rate limit and quota.
Only then does it run the request — as the user who created the token, so that user’s record-sharing rules apply.
The API accepts two kinds of Bearer token:
Token type | What it looks like | Best for | Scopes come from |
|---|---|---|---|
Personal Access Token (API key) |
| Integrations, scripts, Zapier/Make, servers, MCP clients | The scopes you tick when you create it. They never change; create a new key to widen them. |
Your CRM login token | A long token starting | Quick tests in the API reference while you are signed in | Your own profile permissions, checked live on every request. It does not use your plan’s API quota and stops working when you sign out. |
Click the Settings (gear) icon at the bottom of the left rail. In the settings menu, scroll to Developer Hub and click API Keys.

What this screenshot shows. The Settings menu on the left, scrolled down to the Developer Hub group.
The ringed group is Developer Hub, which holds Integrations, WhatsApp API & Docs and API Keys. The arrow points at it.
API Keys is highlighted, which means it is the page currently open on the right.
Above it you can see the other settings groups — Security Control, Customization, Marketing Channels, Sales & Finance, Data Administration and Analytics & Reports. You don’t need any of them for this guide.
The gear icon near the bottom of the dark left rail is selected, showing you are in Settings.

What this screenshot shows. The top of the API & Connections page, where all API keys are managed.
The title API & Connections and its description: “Personal Access Tokens, connected applications, usage tracking, and quota alerts for the … Public REST API.”
Four tabs: Keys (selected — the list of tokens), Connections (apps you authorised, such as Claude), Usage (how many calls were made) and Alerts (warnings before you hit your quota).
The orange Generate API key button on the right creates a new token.
Below the ring: a search box (“Search by label or prefix…”), an All statuses filter and the list of existing keys with their scopes and status.

What this screenshot shows. The column headers of the keys list. Each one tells you something useful about a token.
LABEL — the name you gave the key, with the start of the token (its prefix, e.g. cak_live_EXAMPLEa…) underneath. The prefix is how you recognise a key without exposing the full secret. (Prefixes of real keys are blurred in these screenshots.)
SCOPES — what the key is allowed to do, e.g. “Contacts: Read”.
STATUS — Active, Expired or Revoked. Only Active keys can authenticate.
LAST USED — when the key last made a successful call. “Never” means it has not been used yet.
CREATED — when it was made. ACTION holds the ⋯ menu used to revoke a key.

What this screenshot shows. The Generate API key button at the top right of the Keys tab.
Click it to open the Generate API key window.
The rest of the page (washed out) is the keys list you saw in Step 1. Nothing changes there until you finish creating the key.

What this screenshot shows. The Generate API key window, with the Label field filled in.
The window’s description reminds you: “You’ll see the full token once after generation — copy and store it securely.”
The ringed Label field contains “Website integration”. The hint below it says it is “A human-readable name. Helps you remember what this key is for.” Use a name that says where the key is used, e.g. “Website integration” or “Zapier – new leads”.
Below it is the Scopes section with a Search permissions… box and one block per area of the CRM, each with Read / Write / Delete checkboxes.
The Generate button at the bottom stays pale (disabled) until you have entered a label and ticked at least one scope.

What this screenshot shows. The Scopes list scrolled to Contacts, with Read and Write ticked.
Read — “List, get, search and batch-read Contacts”. Needed for any call that fetches contacts.
Write — “Create, update, upsert and batch-write Contacts”. Needed to add or change contacts.
Delete (left unticked) — “Archive Contacts (soft delete, recoverable for 90 days)”.
Read and Write are independent: ticking Write does not give Read. Tick only what your integration really needs.
Other areas (Companies, Contacts Attachments and so on) appear above and below. Type in Search permissions… to find one quickly.

What this screenshot shows. The Expires drop-down at the bottom of the window, opened.
The options are Never, 30 days, 90 days, 1 year and 2 years.
When a key expires its status changes to Expired and every call made with it is refused with 401.
Pick the shortest period that suits you and put a reminder in your calendar to replace the key before it runs out.

What this screenshot shows. The bottom of the window, ready to create the key.
Expires is set to 90 days, with the hint “Best practice is to rotate keys periodically.”
Above it you can see the last scope groups in the list — Telephony, Plan & Usage, Support and WhatsApp.
The Generate button is now orange (enabled). Click it to create the token, or Cancel to close without creating anything.

What this screenshot shows. The Save this token now window that appears right after you click Generate.
The warning reads: “This is the only time the full token will be shown. Copy it now and store it in a password manager, secret store, or .env file.”
The grey box holds the full token — here the example cak_live_EXAMPLEa7Kq2mVx9Rt4Lp8Zw3Nc6Hd1Fs5Jb0. Yours will be different.
Copy to clipboard copies it exactly, without stray spaces.
I’ve saved it is pale (disabled) until you have clicked Copy — a safety catch so the token isn’t lost by accident.
Behind the window the new key already appears at the top of the list as “Website integration”.

What this screenshot shows. The same window after clicking Copy to clipboard.
The button now reads Copied, confirming the token is on your clipboard.
I’ve saved it is now orange. Paste the token into your password manager or secret store first, then click it to close the window.

What this screenshot shows. The keys list after closing the window. The new key is the ringed first row.
LABEL: “Website integration”, with the token prefix underneath.
SCOPES: Contacts: Read and Contacts: Write — exactly what was ticked.
STATUS: Active, so it can be used straight away.
LAST USED: “Never” — this changes after the first successful call, which is an easy way to confirm your integration is really using this key.
CREATED: “1 minute ago”. The ⋯ button at the end of the row is used in Step 8.
Every request must include this header — the word Bearer, one space, then the full token:
Authorization: Bearer cak_live_YOUR_TOKEN_HERE
Part | What it must be |
|---|---|
Header name |
|
Scheme |
|
Token | The full token, starting |
Base URL |
|
curl (terminal) — list one contact:
curl "https://app.aiengagecrm.com/cback/api/public/v1/objects/contacts?limit=1" \
-H "Authorization: Bearer cak_live_YOUR_TOKEN_HERE"
JavaScript (Node.js 18+ or a server-side function):
const res = await fetch("https://app.aiengagecrm.com/cback/api/public/v1/objects/contacts?limit=1", {
headers: { Authorization: `Bearer ${process.env.AIENGAGE_API_TOKEN}` },
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.category}: ${data.message}`);
Python:
import os, requests
res = requests.get(
"https://app.aiengagecrm.com/cback/api/public/v1/objects/contacts",
params={"limit": 1},
headers={"Authorization": f"Bearer {os.environ['AIENGAGE_API_TOKEN']}"},
)
res.raise_for_status()
print(res.json())
In Postman, open the request’s Authorization tab, choose Bearer Token and paste the token. In Zapier or Make, use an HTTP / Webhooks step and add a header named Authorization with the value Bearer cak_live_….
The CRM has an interactive API reference where you can try your token without writing any code. Open https://app.aiengagecrm.com/cback/api/public/v1/docs in your browser (no sign-in needed to view it).

What this screenshot shows. The top of the API reference page.
The title with the version badges v1 and OAS 3.1 (the OpenAPI format), and a link to the machine-readable openapi.json file.
The dark header bar shows a V1 · READ-ONLY badge and, at the right, links to a ReDoc view (a read-only layout of the same reference) and openapi.json.
The introduction says every endpoint on this page only reads data — none of them create, update, delete or send anything — so testing here is safe.

What this screenshot shows. The Authentication section of the reference, which summarises this article.
“Every endpoint except this document needs Authorization: Bearer <token>.”
1. A Personal Access Token — for integrations, scripts and MCP clients. Created under Settings → API Keys, shown once, scopes frozen at creation, counts against your plan’s API quota, and can carry an IP allowlist.
2. Your CRM login token — for trying things out as yourself. Its scopes follow your profile permissions live, it does not use API quota, and signing out revokes it.
The last line: “Press Authorize above and paste either one to try requests straight from this page.” That is the next step.

What this screenshot shows. What happens if you call an endpoint without a token. This is a real response from the server.
Above the ring, the Curl box and Request URL show what was sent — notice there is no Authorization line in the curl command.
Code 401 — Error: Unauthorized.
The Response body shows the standard error format: "status": "error", "message": "Missing or malformed Authorization header.", "category": "UNAUTHORIZED", a correlationId, an empty errors list and a documentation_url.
The Response headers underneath include api-version: v1 and an x-correlation-id matching the body.
This is the error you get when the header is missing, misspelt, or doesn’t start with Bearer .

What this screenshot shows. The Authorize button with a padlock, at the right of the Servers box, just above Filter by tag and the list of endpoints.
The Servers box on the left shows the address every request is sent to, ending in /cback/api/public/v1.
Above it is the end of the Errors section of the reference; below it the first group of endpoints, Schema & Discovery. Each endpoint row also has a small padlock on its right.
Until you authorize, every “Try it out” request is sent without a token and is refused with 401.
Click Authorize to enter your token once; the page then adds the Bearer header to every request for you.

What this screenshot shows. The Available authorizations window.
It shows a single method, bearerAuth (http, Bearer), with the note: “Either a CRM Personal Access Token (cak_live_…, created under Settings → API Keys) or your own CRM login JWT. Send it as Authorization: Bearer <token>.”
The Value box contains the example token. Paste only the token here — the page adds the word Bearer itself.
Click Authorize to save it, or Close to leave without changing anything.

What this screenshot shows. The same window after clicking Authorize.
The token is now hidden (shown as asterisks) and the window confirms you are Authorized.
Logout removes the token from this page — use it on a shared computer. Close returns to the reference.

What this screenshot shows. The Authorize button after closing the window.
The padlock icon now shows the page is authorized, so every request you run from this page carries your token.
The token stays saved on this page across reloads until you click Authorize → Logout.
Now open an endpoint, for example GET /objects/{module}, enter contacts in module and 1 in limit, then click Execute.

What this screenshot shows. The result when the token itself is wrong. This is a real response — the example token does not exist.
Code 401 with "message": "Invalid or revoked token." and "category": "UNAUTHORIZED".
The header was sent correctly this time, but the CRM did not recognise the token. You get exactly the same answer for a token that was mistyped, cut short when copying, revoked, expired, or whose creator has been deactivated.
If you see this with your real key: check its STATUS on the API Keys page is Active, and copy it again from your password manager.

What this screenshot shows. The Curl box and Request URL the reference generates when you click Execute.
The curl command shows exactly what was sent, including the line -H 'Authorization: Bearer cak_live_EXAMPLE…'. Copy it into a terminal to repeat the same call.
The Request URL shows the full address, ending in /objects/contacts?limit=1.
Compare this with your own code if your integration fails but the reference works — the difference is usually in the header.

What this screenshot shows. A successful call. The data is an example contact in the real response shape.
Code 200 means the token was accepted, it had the crm.contacts.read scope, and the request ran.
results holds the records — each with an id, its field values under properties (first_name, last_name, email, phone and so on), and created_at / updated_at dates.
paging.next.after is a cursor: send it as after in your next request to get the next page.
Only records the token’s creator can see in the CRM are returned — sharing rules apply to API calls too.

What this screenshot shows. The Response headers of the successful call.
ratelimit-limit — how many requests this token may make in the current window (100 every 10 seconds for most endpoints).
ratelimit-remaining — how many are left in this window. ratelimit-reset — seconds until the window starts again.
x-correlation-id — a unique id for this request. Quote it when you contact support about a call.
api-version: v1 — the API version that answered.
Every error uses the same JSON format, so your code can read category to decide what to do:
{
"status": "error",
"message": "Invalid or revoked token.",
"category": "UNAUTHORIZED",
"correlationId": "01KYEXAMPLE0CORRELATION0ID",
"errors": [],
"documentation_url": "…"
}
Status | Message / category | What it means | How to fix it |
|---|---|---|---|
401 | “Missing or malformed Authorization header.” · | No | Send |
401 | “Invalid or revoked token.” · | The token is unknown, mistyped, revoked or expired, or the user who created it has been deactivated. | Check the key is Active on the API Keys page. If it isn’t, or you aren’t sure the copy is complete, generate a new key. |
401 | “Test-mode tokens are not yet supported.” | A token starting | Use a |
403 | “Token is missing required scope: crm.contacts.read” · | The token is valid but wasn’t given the scope this endpoint needs. The body also includes | Generate a new key that includes that scope (scopes can’t be added to an existing key). See API Token Scopes & Permissions. |
403 | “Source IP is not in the token allowlist.” · | The key is limited to certain IP addresses and the call came from another one. | Call from an allowed server, or use a key without that restriction. |
403 | “API access is not included in your current plan…” · | Your subscription doesn’t include the public API. | Upgrade the plan, or contact your account owner. |
429 | “Rate limit exceeded for token cak_live_…” · | Too many requests too quickly, or the daily/monthly API quota is used up. | Wait the number of seconds in the |
GET https://app.aiengagecrm.com/cback/api/public/v1/ping with the header. It needs no scope and answers "message": "pong" when the token is accepted, so if ping works but another endpoint returns 403, the problem is a missing scope — not the token.Revoke a key when an integration is retired, a team member who managed it leaves, or you think the token may have been exposed. Then create a replacement and update your integration.

What this screenshot shows. The ⋯ menu at the end of the “Website integration” row, opened.
The menu has one option, Revoke, with a bin icon.
Keys can’t be edited. To change a key’s scopes or expiry, generate a new one and revoke the old one.

What this screenshot shows. The confirmation that appears before a key is revoked.
The title asks Revoke this API key?
The message names the key by its prefix: “The token cak_live_EXAMPLEa… will stop working immediately on the next API call. This cannot be undone — any service using this token will need a new one.”
Click the red Revoke button to confirm, or Cancel to keep the key.

What this screenshot shows. The same row after revoking.
STATUS now shows Revoked in red. The row stays in the list as a record.
From this moment any request using this token gets 401 “Invalid or revoked token.”
Use the All statuses filter above the list to show only Active, Expired or Revoked keys.
Generate a new key with the same scopes and a clear label, e.g. “Website integration (2027)”.
Update the token in your integration’s environment variable or secret store and redeploy / save.
Watch the new key’s LAST USED column change from “Never”, and the old key’s stop updating.
Revoke the old key.
Create one key per integration, so you can revoke one without breaking the others, and see which one is busy on the Usage tab.
Tick the fewest scopes the integration needs — read-only where possible.
Choose an expiry and rotate keys before they expire.
Store tokens in a password manager or secret store, never in code, e-mails or chat.
Always call the API over HTTPS and only from servers you control.
Review the Keys list regularly and revoke keys whose LAST USED shows they are no longer needed.
Is an API key the same as a Bearer token?
Yes. In AiEngage CRM the API key is the Bearer token: a Personal Access Token starting cak_live_. “Bearer” is simply the word you put in front of it in the Authorization header.
Can I see a token again after creating it?
No. It is shown once. The list only keeps its prefix. Generate a new key if it’s lost.
Can I pass the token in the URL instead of a header?
No. The API only reads the Authorization header. Tokens in URLs also end up in logs, which is unsafe.
Whose permissions does a key use?
The permissions of the user who created it. If that user can only see their own records, so can the key; if the user is deactivated, the key stops working (401).
Do I need OAuth?
Not for your own integrations — a Personal Access Token is enough. Apps such as Claude connect through an approval screen instead and appear on the Connections tab; see Connect Claude to AiEngage CRM (MCP).
How many requests can I send?
Each key can make up to 100 requests every 10 seconds on most endpoints (searches are limited more tightly), and all keys share your plan’s daily and monthly quota. Read the RateLimit-* headers to pace your calls.
OpenAI Engage and apply what you just learned to your own workspace.
Open AI Engage CRM