StaqOn API

Authentication

Every request must send your API key in a header:

Base URL

Each surface has its own base. Endpoints below are relative to [base_url] for their surface:

Which surface?

There are six real, distinct concepts on this page, not two. Four are API surfaces your CRM calls (or is called by); two are identity-verification mechanisms, separate from messaging entirely. Mixing these up — especially the two pairs that share a word ("Internal", "Chatbot") — is the single most common source of confusion integrating against StaqOn.

A key is bound to the surface of the team it was created against. This is the thing people get wrong first.

Everything is key-only except the endpoints listed below. Those return 403 until the member's staqon_links row is approved, and again the moment it's revoked.

Consent is governed by staqon_links — one row per (workspace, member, surface) — StaqOn's replacement for the old, removed per-team account-linking flow this section used to describe. The old /link-request.php//link-status.php//link-revoke.php endpoints and the Account settings → Linking Requests tab no longer exist.

The two surfaces now work in opposite directions:

See the Link API and Internal Link API sections above for each flow's full, literal request examples.

Rate limiting

100 requests/minute per key, rolling 60-second window — a real 429 "Rate limit exceeded. Max 100 requests/minute." with a Retry-After header when exceeded. This is the same limit for every endpoint on both surfaces — there is no per-endpoint override, so it is documented once here rather than repeated on each endpoint below.

20,000 requests/day per key, on top of the per-minute limit above, resetting at midnight Asia/Kolkata (IST). A real 429 when exceeded: {"ok":false,"error":"Daily API limit reached (20,000 requests). Resets in 3h 12m.","retry_after_seconds":11520}, with a matching Retry-After header (seconds until midnight IST). Both limits are checked on every authenticated request; whichever is hit first returns its own 429.

External API

Partner teams. Two-way. Writes need only the key. Base: https://staqon.one/api/v1/external

Internal API

Your own staff. One-way. Writes need an approved link. Base: https://staqon.one/api/v1/internal

Card format

Both comment.php (External) and message.php (Internal) accept an optional card object alongside the plain-text fallback (comment / message), rendering a structured card instead of plain text. The fallback text is still required and is used for push notifications and older clients.

{
  "header_color": "#059669",
  "title": "Approved — ₹5,000",
  "body": "Your wallet topup has been approved and credited.",
  "button": { "label": "View transaction", "url": "https://vistarkriya.com/wallet/txn/1234", "color": "#059669" }
}

{
  "header_color": "#DC2626",
  "title": "Payment failed",
  "body": "Your last payment attempt did not go through.",
  "button": { "label": "Retry payment", "url": "https://vistarkriya.com/wallet/retry/1002", "color": "#DC2626" }
}

{
  "header_color": "#D97706",
  "title": "KYC re-verification needed",
  "body": "Your KYC documents expire in 5 days.",
  "button": { "label": "Update KYC", "url": "https://vistarkriya.com/kyc/update", "color": "#D97706" }
}

{
  "header_color": "#2563EB",
  "title": "Application received",
  "body": "Your loan application is now under review.",
  "button": { "label": "Track status", "url": "https://vistarkriya.com/loan/LN-4521", "color": "#2563EB" }
}

{
  "header_color": "#0891B2",
  "icon": "pending",
  "meta_title": "MLS lead",
  "title": "Update \u2014 Applicant Name",
  "body": "Reference: **MLS26-T064-DB585C**\nStatus: *InProgress*\n\n- Received by partner\n- Awaiting document review\n- Next update within 24h"
}

{
  "username": "4821k9037",
  "message": "Payout processed. ₹12,500 released.",
  "external_ref": "crm-9005",
  "link_url": "https://crm.example.com/payouts/9005/receipt",
  "card": {
    "header_color": "#059669",
    "meta_title": "Payout",
    "title": "₹12,500 released",
    "body": "Your September payout has been released to your registered bank account.",
    "sub_body": "Reference: PAYOUT-9005",
    "button": { "label": "View payout", "url": "https://crm.example.com/payouts/9005", "color": "#059669" }
  }
}

External Chatbot API

Real, live /help answers powered by your own CRM. Unlike the two surfaces above, this is an inbound contract from your side — StaqOn calls a webhook URL on your server, synchronously, while a real external member waits for the answer.

Internal Chatbot API

Real, live Internal /help answers powered by your own CRM (2026-09-05) — the same real, inbound mechanism as the External Chatbot API above, aimed at your own staff instead of external partner/customer members. StaqOn calls a webhook URL on your server, synchronously, while a real internal staff member waits for the answer in their team's own group conversation.

Internal /help — the real 3-stage gate

A staff member types /help literally, inside their internal team's own group conversation (not a guest thread — internal teams have no guest concept; any genuine roster member typing it triggers this). api/messages.php resolves the conversation via icb_internal_team_conv_team_id() (must be a real type='group', is_external_thread=0 conversation belonging to a real, non-archived team_type='internal' team, and the sender must be on that team's roster) — anything else and /help falls straight through as an ordinary literal message, never a silent no-op. Structural mirror of External's own 3-stage gate, in the exact same order:

All three stages passed → StaqOn builds a real bot_menu from this team's root internal_chatbot_nodes (icb_build_menu_from_nodes()), validates it (icb_validate_bot_menu() — byte-for-byte mirror of External's validate_bot_menu()), and sends it via icb_send_bot_message() into the team's own conversation, attributed to the triggering staff member (not the key's created_by) — responds {"ok":true,"intercepted":"internal_help"}.

Internal Chatbot API — admin setup

Configured from Workspace → Settings → API → Internal Chatbot API (app/internal-chatbot-teams.php, owner/admin only, gated by require_workspace_member() + role check — identical auth model to every other admin surface on this page). Every real internal team in the workspace is listed, configured or not (a genuine LEFT JOIN internal_chatbot_keys, not a filtered list) — an unconfigured team's card links straight to the edit page's first-time-setup form rather than a dead end.

api/internal-chatbot-keys.php: create (rejects a second active key for a team already configured — "This team already has an active chatbot key. Revoke it first."), list, rotate (15-minute grace period on secret only — the sk_bot_ bearer key/hash is untouched, since nothing verifies it inbound today), revoke. The webhook URL is validated as a well-formed public http(s):// address (SSRF guard against private/loopback ranges) but never actually called at creation time — same honest gap as Link/Internal Link's own webhook setup.

api/internal-chatbot-nodes.php: list/create/update/delete against internal_chatbot_nodes, a real self-referential adjacency-list table (parent_id → id, ON DELETE CASCADE). Each node carries: question (max 255 chars), answer_type (static or api), answer_text (required for static), link_url (optional, static-only, must be genuine https://, max 500 chars), query_type (required for api — this is the exact free-text tag your webhook receives; free text by default, optionally validated at save time against the key's registered list if one exists, see the callout above), prompt_text/validation_type/validation_length (optional, api-only free-text capture), and follow_up.

Set on an api-type node alongside a real prompt_text. Byte-for-byte mirror of External's own chatbot_validate_free_text(), confirmed by reading icb_validate_free_text() directly:

Link API

/link is StaqOn's workspace-wide identity-linking mechanism. Since 2026-10-15 an External member is linked with a single-use invite token that your CRM requests from StaqOn and delivers to its own customer — the customer then confirms on StaqOn. One Link API key per workspace carries the workspace's webhook URL, its shared secret and its event subscriptions, all in one place.

One key per workspace, generated from Workspace → Settings → API → Link (or the dedicated Link API admin page it links to). You provide a webhook URL; StaqOn generates the bearer key and the shared secret. The secret is shown exactly once, at generation time — store it immediately, it is never re-displayed. There is nothing else to configure: no question to set.

The same real checkbox list as the Webhooks section below — pick which of the seven real events this workspace's webhook receives. Subscriptions can be changed at any time without rotating the key or the webhook URL. (The one exception is the approval event of an invite you issued — see below: it is always delivered.)

Same grace-period pattern as every other surface on StaqOn: rotating generates a new secret immediately while the previous one stays valid for a real 15-minute window, so an in-flight integration is never broken by a rotation.

A you call StaqOn endpoint, HMAC-signed exactly like link-list.php — no X-API-Key. Only External Link keys can request invites.

POST /api/link-invite.php
Content-Type: application/json
X-StaqOn-Signature: t=<unix_timestamp>,v1=<hex>

{
  "key_id": 24,
  "timestamp": "2026-10-15T06:32:44Z",
  "email": "customer@example.com",
  "external_ref": "CRM-10492"
}

Signature. Same as link-list.php: hash_hmac('sha256', "{unix_timestamp}.{raw_body}", your_link_secret), sent as X-StaqOn-Signature: t=<unix_timestamp>,v1=<hex>; the bare-hex form (hash_hmac('sha256', raw_body, secret), no t=) is also accepted. The body's timestamp (and the t= value, when used) must be within ±5 minutes. During the 15-minute grace window after a secret rotation, a request signed with your previous secret is still accepted.

{
  "ok": true,
  "token": "lnk_3f9c…(64 hex characters)",
  "short_code": "K7M2QX",
  "expires_in": 3600,
  "confirm_url": "https://staqon.one/app/link-confirm.php?token=lnk_3f9c…"
}

An HTML page in the StaqOn app, not a JSON endpoint, so it isn't in the OpenAPI spec. The customer must be logged in to StaqOn and be a guest member of your workspace (sub-users cannot link). It works in two steps, and the invite is named either by the link (?token=…) or by the short code (?code=ABC123): step 1 asks for the email address you gave link-invite.php — nothing about the invite is shown yet; step 2, only if the email matches, names your workspace and shows the customer's own StaqOn account email with Yes and No. Yes approves the link and burns the token and short code; No declines the invite and burns them. Nothing is sent to you when the customer declines or the invite expires.

Entering a code instead of a link. "Link this workspace" and typing /link (or the first /help for an unlinked member) in chat no longer ask for an email and an answer. They open one popup with two fields — Link code and Email — submitted together. The Link code box accepts the 6-character short code (any case, spaces or dashes ignored), the long token, or the whole confirm_url. On Submit the app checks the pair with invite_lookup (the same call described below); a wrong code, a wrong email, or a used or expired code all show the same message in the popup — "That code and email don't match" — and consume nothing. When the pair matches, the popup moves on to your workspace name, the member's own account email and Yes / No, which call invite_confirm; the member never leaves the page. Someone who opens a shared confirm_url directly, without the popup, still gets the page described above: email first, then Yes / No.

/app/link-confirm.php needs the browser's cookie session, but the StaqOn mobile app authenticates every call with Authorization: Bearer <token> and has no cookies — so it can't use that page. For that case the same confirm step is exposed as two JSON actions on /api/link.php. They run exactly the same logic as the web page (one shared implementation), so a token behaves identically on both surfaces. These are member-side calls made by the StaqOn app, not something your CRM calls — your CRM only ever calls link-invite.php. Documented for completeness and for anyone building a client.

Common to both actions: POST /api/link.php?action=…&w=<workspace_slug>, JSON body, Authorization: Bearer <the member's app session token>. The caller must be an active guest (not a sub-user) of the workspace. Every request must carry email — the address the business gave (the invite's crm_email) — and one identifier: token or short_code. If both are sent they must belong to the same invite, or the request fails generically. The app sends the raw token (lnk_…) or the 6-character code (case-insensitive): a pasted confirm_url is rejected, so the client extracts the token (or code) value first. (Web-cookie callers also need a CSRF token; Bearer callers don't.) Changed 2026-10-15: email is now mandatory on every call — a call without it, or with one that doesn't match, gets the same generic 400 as an unknown code.

POST /api/link.php?action=invite_lookup&w=acme-corp
Authorization: Bearer <member app-session token>
Content-Type: application/json

{ "email": "customer@example.com",
  "token": "lnk_3f9c…(64 hex characters)" }     // or  "short_code": "K7M2QX"  instead of "token"

200 { "ok": true,
      "business_name": "Acme Corp",
      "account_email": "customer@example.com",
      "external_ref": "CRM-10492" }

account_email is the member's own StaqOn account email. crm_email is intentionally not returned (the web page hides it too). A lookup changes nothing: the invite stays pending until invite_confirm.

POST /api/link.php?action=invite_confirm&w=acme-corp
Authorization: Bearer <member app-session token>
Content-Type: application/json

{ "email": "customer@example.com",
  "short_code": "K7M2QX",                       // or  "token": "lnk_3f9c…"
  "decision": "yes" }                           // or "no"

200 { "ok": true, "status": "approved" }          // or "declined"

• Yes — the token is burned (single-use), staqon_links is set to approved with the invite's external_ref and crm_email, and one link.status_changed webhook goes to your External Link key regardless of its event subscription (see the approval webhook).
• No — the token is burned, no link row is created and no webhook is sent.
• Conflict — if your external_ref is already linked to a different StaqOn account: 409 {"ok":false,"error":"Couldn't link: this customer is already linked to a different StaqOn account. Please contact the business."}. The invite stays pending and nothing changes.
• Replay — confirming a token or code that was already used gets the same generic 400 as an unknown one, with or without the correct email; a client cannot tell "already used" from "never existed".

When the customer taps Yes, StaqOn POSTs to your Link webhook URL (the same URL and secret as your other events, one attempt, 5s timeout, no retry):

POST <your webhook_url>
Content-Type: application/json
X-StaqOn-Signature: <hex>
X-StaqOn-Event: link.status_changed

{
  "event": "link.status_changed",
  "timestamp": "2026-10-15T12:04:11+05:30",
  "data": {
    "user_id": 2,
    "username": "4821k9037",
    "link_type": "external",
    "status": "approved",
    "workspace_id": 1,
    "team_id": 0,
    "external_ref": "CRM-10492",
    "crm_email": "customer@example.com"
  }
}

A real, working, read-only endpoint (2026-09-02) — the reverse direction from every other call on this page: you call StaqOn, HMAC-signed the same way the health endpoint verifies your inbound calls. Use it to show your own customers their real-time connection status on your own site, or to reconcile your own records against StaqOn's.

POST /api/link-list.php
Content-Type: application/json
X-StaqOn-Signature: t=<unix_timestamp>,v1=<hex>

{
  "key_id": 24,
  "timestamp": "2026-09-02T06:32:44Z"
}

key_id is your Link API key's numeric ID (shown on the Link admin page once configured). timestamp is an ISO-8601 string, checked for a real ±5 minute freshness window — same convention as the health endpoint. The signature covers the raw request body: hash_hmac('sha256', "{unix_timestamp}.{raw_body}", your_link_secret), sent as t=<unix_timestamp>,v1=<hex>. The older bare-hex format (no t= prefix) is also accepted, matching every other signature check on StaqOn.

{
  "ok": true,
  "links": [
    {
      "crm_email": "customer@example.com",
      "link_type": "external",
      "username": "4821k9037",
      "status": "approved",
      "linked_at": "2026-09-02 12:02:30"
    }
  ]
}

{"ok": false, "error": "Invalid signature or unknown key."}

$keyId = 24;                       // your real Link API key's id
$secret = 'lnksec_...';            // your real Link API secret
$timestamp = gmdate('Y-m-d\TH:i:s\Z');
$body = json_encode(['key_id' => $keyId, 'timestamp' => $timestamp]);
$unix = time();
$sig  = 't=' . $unix . ',v1=' . hash_hmac('sha256', $unix . '.' . $body, $secret);

$ch = curl_init('https://staqon.one/api/link-list.php');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $body,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'X-StaqOn-Signature: ' . $sig],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = json_decode(curl_exec($ch), true);
// $response['links'] — your workspace's real, current approved External connections

Internal Link API

/link's Internal surface (2026-09-02) — a genuinely separate mechanism from the External Link API above, for linking your own staff's StaqOn identity to your CRM, rather than an external customer's. Its own dedicated table (internal_link_keys), its own admin page (Workspace → Settings → API → Link API → For Internal), its own key/secret/webhook/events, independent from External's.

One key per workspace, generated from the Internal Link admin page. You provide a webhook URL; StaqOn generates the bearer key and the shared secret. The secret is shown exactly once, at generation time — store it immediately, it is never re-displayed.

A staff member types /link in chat (a real two-step conversation: CRM ID first, then email) or uses the direct-click popup (both fields in one submission). StaqOn HMAC-signs and POSTs both to your Internal Link webhook URL. The member's staqon_links row (link_type='internal') is marked approved only if your webhook responds {"ok": true} — a genuine CRM-verified handshake, matching External's own rigor, not an automatic approval on bare free text.

POST <your webhook_url>
Content-Type: application/json
X-StaqOn-Signature: <hex>
X-StaqOn-Trace-Id: <uuid>
X-StaqOn-Event: internal_link.verify

{
  "crm_id": "CRM100",
  "email": "staff@yourcompany.com",
  "username": "4821k9037",
  "trace_id": "b3f1c2a4-7e5d-4a91-9c2e-1f6a8d0b3c5e"
}

The signature is bare hex — hash_hmac('sha256', raw_body, your_internal_link_secret) — sent as X-StaqOn-Signature, same outbound-call convention as External's own verify contract above (no t=/timestamp component — this is StaqOn calling you, not the reverse).

{"ok": true}

Internal Link keys carry their own independent events subscription list — genuinely separate from the External Link key's own subscriptions, even though both can subscribe to the same real event name. Today the only real event available here is link.status_changed, fired on a real Internal /link approval or revoke.

{
  "event": "link.status_changed",
  "timestamp": "2026-09-02T15:52:15+05:30",
  "data": {
    "user_id": 2,
    "username": "4821k9037",
    "link_type": "internal",
    "status": "approved",
    "workspace_id": 1,
    "team_id": 0
  }
}

Same real delivery discipline as every other webhook on StaqOn: X-StaqOn-Signature is a bare-hex HMAC-SHA256 of the raw body, keyed by your Internal Link secret, plus an X-StaqOn-Event header. One delivery attempt, no retry, no queue. status is "approved" or "revoked"; team_id is always 0 — /link has no team concept, it's workspace-scoped. username (added 2026-09-03) is StaqOn's own real username for the linked person, already resolved before the event fires — no separate lookup needed.

Same real grace-period pattern as every other surface: rotating generates a new secret immediately while the previous one stays valid for a real 15-minute window.

A real, working, read-only endpoint (2026-09-02) — the reverse direction from your Internal Link webhook, direct structural mirror of the External Link API's own link-list.php: you call StaqOn, HMAC-signed the same way the health endpoint verifies your inbound calls. Use it to check a staff member's real-time link status from your own system, or to reconcile your own records against StaqOn's.

POST /api/internal-link-list.php
Content-Type: application/json
X-StaqOn-Signature: t=<unix_timestamp>,v1=<hex>

{
  "key_id": 15,
  "timestamp": "2026-09-02T06:32:44Z"
}

key_id is your Internal Link API key's numeric ID (shown on the Internal Link admin page once configured). timestamp is an ISO-8601 string, checked for a real ±5 minute freshness window — same convention as every other real signature check on StaqOn. The signature covers the raw request body: hash_hmac('sha256', "{unix_timestamp}.{raw_body}", your_internal_link_secret), sent as t=<unix_timestamp>,v1=<hex>. The older bare-hex format (no t= prefix) is also accepted.

{
  "ok": true,
  "links": [
    {
      "crm_username": "CRM100",
      "crm_email": "staff@yourcompany.com",
      "username": "4821k9037",
      "status": "approved",
      "linked_at": "2026-09-02 16:29:42"
    }
  ]
}

{"ok": false, "error": "Invalid signature or unknown key."}

$keyId = 15;                            // your real Internal Link API key's id
$secret = 'ilnksec_...';                // your real Internal Link API secret
$timestamp = gmdate('Y-m-d\TH:i:s\Z');
$body = json_encode(['key_id' => $keyId, 'timestamp' => $timestamp]);
$unix = time();
$sig  = 't=' . $unix . ',v1=' . hash_hmac('sha256', $unix . '.' . $body, $secret);

$ch = curl_init('https://staqon.one/api/internal-link-list.php');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $body,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'X-StaqOn-Signature: ' . $sig],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = json_decode(curl_exec($ch), true);
// $response['links'] — your workspace's real, current approved Internal (staff) connections

Webhooks

StaqOn POSTs a JSON callback to your subscribed URL when a workspace event fires. As of 2026-09-01, webhooks are configured as part of your Link API key — one webhook per workspace (not per team, as this section used to describe), using the same URL and shared secret as your Link key. Pick which events you want at Workspace → Settings → API → Link.

PHP:
$raw = file_get_contents('php://input');
$expected = hash_hmac('sha256', $raw, $yourWebhookSecret);
if (!hash_equals($expected, $_SERVER['HTTP_X_STAQON_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit;
}

Node.js:
const crypto = require('crypto');
const expected = crypto.createHmac('sha256', yourWebhookSecret).update(raw).digest('hex');
const sig = Buffer.from(req.headers['x-staqon-signature'] || '', 'utf8');
const exp = Buffer.from(expected, 'utf8');
const valid = sig.length === exp.length && crypto.timingSafeEqual(sig, exp);
if (!valid) return res.status(401).end();

Python:
import hmac, hashlib
expected = hmac.new(your_webhook_secret.encode(), raw_body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, request.headers.get('X-StaqOn-Signature', '')):
    return Response(status=401)

{
  "event": "<name>",
  "timestamp": "<ISO-8601>",
  "data": { }
}

Health endpoint

POST /api/webhook-health.php?action=check — a single, read-only, unified endpoint shared across External, Internal and Chatbot. Lets you check your own key/webhook's real status without ever transmitting your secret over the wire.

{
  "surface": "external",
  "key_id": 123,
  "timestamp": "2026-08-30T12:00:00Z"
}

{
  "ok": true, "surface": "external", "is_active": true, "revoked_at": null,
  "last_used_at": "2026-08-30 11:27:24", "usage_count": 881,
  "authenticated_with": "current",
  "bearer_key_rotation": { "grace_period_active": false },
  "webhook": { "is_active": true, "failure_count": 0, "last_triggered_at": "2026-08-27 11:45:55" },
  "grace_period_active": false
}

{
  "ok": true, "surface": "chatbot", "is_active": true, "failure_count": 0,
  "warned_at": null, "last_used_at": "2026-08-30 14:34:30", "revoked_at": null,
  "authenticated_with": "current", "grace_period_active": false
}

Secret rotation

A rotate action now exists per surface (api/api-keys.php's rotate / webhook_rotate, api/chatbot-keys.php's rotate) — generates a brand-new secret/key immediately while keeping the previous one valid for a real 15-minute grace window. This replaces the old revoke-and-recreate pattern, which had zero overlap and would break an in-flight integration instantly.

The health endpoint's response includes rotation state when relevant: grace_period_active, previous_secret_expires_at, minutes_remaining. External/Internal additionally carry a separate bearer_key_rotation block, since the bearer key (api_keys) and the webhook secret (webhooks) rotate independently of each other.

Cross-API trace IDs

Every request across all three surfaces now supports X-StaqOn-Trace-Id: an optional request header, always present on the response.

A member taps /help → the External Chatbot API fires an outbound query to your CRM, tagged with a trace ID (both as a trace_id field in the JSON body and as the X-StaqOn-Trace-Id header) → your CRM later posts a reply to that same member via the External API, including that same trace ID on the call. Both real events are now queryable together by trace ID — the two separate API calls (different surface, different endpoint, different timing) are provably one logical transaction.

Postman collections

One collection per surface — deliberately separate, so a request can't be copied from one surface to the other and fail with a 400. Import, set apiKey + baseUrl once, and run every endpoint.