API overview & authentication

CXGear exposes an HTTP API for the web app and for external systems (CRMs, middleware, scripts). This page is the map: who authenticates how, and where to send requests.

You do not need to be a platform engineer to follow it — if you integrate CXGear with another product, start here.

Two ways to authenticate

Audience	Credential	Typical use
People in the browser	User JWT (session token after login)	Everything the UI does
External systems	Organization API key (`cxg_…`)	Ingest rows, trigger published spinners

Mixing them up is the most common integration mistake. A browser session token is not an API key, and an API key cannot open the full admin UI.

User JWT (session)

When someone signs in, CXGear issues a short-lived access token (JWT). The web app sends it as:

Authorization: Bearer <access_token>

That token is tied to:

One user
One organization
One active session (see Single active session)

If the session expires, is revoked, or is replaced on another device, API calls return auth errors and the UI sends the person back to login.

Use JWTs only for interactive clients you control (the official web app, or a trusted internal tool that completes login). Do not embed a personal JWT in a CRM or shared middleware.

Organization API keys

API keys let systems act for the organization without a human session.

Keys start with cxg_
You create them under user menu → API keys
The secret is shown once — store it in your secrets manager
Keys have scopes such as ingest and trigger

Authorization: Bearer cxg_your_key_here

See Org API keys and Public ingest & trigger.

Screenshot needed

API keys page with generate action and a key row (prefix only).

Where: User menu → API keys

Save as: src/assets/screenshots/29-api-keys.png

Base URL

All versioned routes live under /api/v1 on your API host.

Environment	Base URL
Production	`https://api.cxgear.ai/api/v1`
Local	`http://localhost:3000/api/v1`

Examples:

POST https://api.cxgear.ai/api/v1/public/ingest
POST https://api.cxgear.ai/api/v1/public/trigger/{spinnerId}
POST https://api.cxgear.ai/api/v1/auth/login

Your deployment may use a different host. The important part is: call the API host, not the web app host (app.cxgear.ai) and not the docs host (docs.cxgear.ai).

Interactive OpenAPI docs (when the API is running):

https://api.cxgear.ai/docs
http://localhost:3000/docs

See OpenAPI / Swagger.

Public vs authenticated routes

Route style	Auth	Purpose
`/auth/…`	Public (credentials in body)	Sign up, login, password reset
Most `/projects`, `/spinners`, …	User JWT	Product UI and admin tools
`/public/ingest`, `/public/trigger/…`	API key + scope	CRM / middleware automation
`/public/data-tables/ingest/:token`	Table ingest token in URL	Per-table webhook (no org key)
Channel OAuth callbacks	Provider-specific	WhatsApp / Meta redirects

Webhook and callback URLs must use the public API URL (PUBLIC_API_URL in deployment). See Webhooks & callbacks and Deployment notes.

Plan limits still apply

API keys do not bypass billing. Creating resources or starting jobs through the public API enforces the same plan meters as the UI. Failures return PLAN_LIMIT — see Rate limits & errors.

Success looks like

Browser traffic uses JWTs; automation uses API keys
Integrators call the correct API base URL over HTTPS
Keys are scoped narrowly (ingest and/or trigger only as needed)
Secrets never appear in frontend code or public repos

Common problems

Problem	Likely cause	What to do
401 Invalid API key	Wrong key, revoked key, or missing `Bearer`	Regenerate key; check header format
403 Key missing scope	Key lacks `ingest` or `trigger`	Create a key with the right scopes
Calls hit the web app URL	Using `app.` instead of `api.`	Switch to the API base URL
Session errors in a script	Using a user JWT in middleware	Switch to an org API key
Works locally, fails in prod	Wrong host or HTTP vs HTTPS	Align with deployment `PUBLIC_API_URL`