Authentication

There are two ways to authenticate, and only one of them is right for an integration.

API keys — for anything that is not a person

A key belongs to the business rather than to a member of staff. It does not expire in fifteen minutes, it does not need refreshing, and it keeps working when the person who created it goes on leave.

Creating one

1. Sign in and go to Settings → API keys & webhooks.
2. Choose New key and name it after the thing that will use it — “Website contact form”, not “test”.
3. Grant only the permissions that integration needs. A form that creates leads needs create on leads and nothing else.
4. Set an expiry if the integration is temporary.
5. Copy the key. It is shown once and never again — only a hash is stored, so we cannot recover it for you.

Using it

Send it in the Authorization header:

curl https://app.jaicrm.ai/api/crm/customers 
  -H 'Authorization: Bearer bb_a1b2c3d4.YOUR_SECRET'

Or, if a header called Authorization is awkward in your tooling, use X-API-Key:

curl https://app.jaicrm.ai/api/crm/customers 
  -H 'X-API-Key: bb_a1b2c3d4.YOUR_SECRET'

Sessions — for the app itself

The web and mobile clients sign a person in at POST /api/auth/login and receive a short-lived token that is refreshed as it expires. This exists for interactive sessions. Do not use it for an integration: it means storing somebody’s password, and it stops working when they change it.

What a key can do

• Exactly the permissions granted when it was created — nothing more.
• Only within its own business. Isolation is enforced in the database, not in application code.
• Nothing in a module that is switched off, which returns 403 naming the module.
• Nothing on the platform control plane, which is not open to tenant keys.

Work done by a key is recorded in the audit trail against the person who created it, so every change has a name against it.