Quickstart
Three steps to your first API call. You need a scoped key, which you create under Settings → Developers → API Keys. Keys are shown once at creation and stored hashed — if you lose one, revoke it and issue another rather than asking support to retrieve it.
# 1. Create a scoped key in Settings → Developers → API Keys
export SHUBHAM_KEY="sk_live_••••••••"
# 2. Read something
curl https://api.shubham.ai/v1/contacts \
-H "Authorization: Bearer $SHUBHAM_KEY"
# 3. Send a template message
curl -X POST https://api.shubham.ai/v1/channels/whatsapp/messages \
-H "Authorization: Bearer $SHUBHAM_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "cnt_4820",
"template": "order_shipped_v3",
"variables": { "name": "Priya", "tracking": "BLR-4821" }
}'
Sandbox keys use the same endpoints and the same response shapes. Nothing is delivered and nothing is billed, so you can build a whole integration before connecting a real number.
Core concepts
Four ideas explain most of how the platform behaves.
Everything is a plugin
Each capability owns its routes, permissions, settings, navigation, events and API endpoints. The core never imports a plugin — plugins register themselves. That is why a plugin you have not licensed has no routes at all, rather than hidden ones.
Plugins communicate through events
A plugin that reacts to a payment subscribes to payment.completed. It never imports the payments plugin. This is what makes any plugin genuinely removable.
Every read is tenant-scoped
There is no ambient “current tenant”. Functions that touch tenant data take a scope, so forgetting to scope a query is a type error rather than a production incident.
AI asks for a purpose, not a vendor
Plugins request chat, classify, extract and so on. The gateway resolves that to a provider using tenant policy, which is why switching model provider is a settings change.
Authentication
All API requests use a bearer token in the Authorization header. Keys are scoped to a tenant and to a set of permissions, and can carry a rate limit and an expiry.
- Never send a key from a browser. A key in client-side JavaScript is a key you have published. Proxy through your own backend.
- Scope narrowly. A key that only reads contacts should hold only
contact.view. Breach impact is bounded by what you granted. - Rotate on a schedule. Issue the replacement, migrate, then revoke — keys can overlap so rotation needs no downtime.
Tenancy and isolation
Tenants form a tree: platform → master partner → partner → business → team. Access runs downward only. A partner may read the tenants beneath it; nothing reads sideways or upward, including two partners under the same master.
The check tests the target’s ancestry, not the caller’s. Testing the caller’s would grant a child access to its parent — backwards, and an easy mistake to make.
Support impersonation requires a written reason of at least ten characters and produces an immutable audit entry recording actor, time and duration.
Permissions
Permissions are strings in a central registry. A permission the session lacks removes the route, the navigation entry and the action control — not just the button.
// Permissions are <resource>.<action> strings from a central registry.
// A plugin declares what it needs; it never invents one at the call site.
permissions: ["campaign.view", "campaign.create", "campaign.send"]
// Wildcards are supported for a whole resource:
// "inbox.*" grants every inbox permission
// "*" grants everything (super admin only)
Events
Around 45 platform events across tenancy, plugin lifecycle, CRM, messaging, money, AI, automation and channels. Events are facts in the past tense, and every one carries its tenant in meta.
// Plugins talk to each other through events, never imports.
subscribes: {
"payment.completed": async (event) => {
// event.payload is typed per event name.
const { paymentId, amountMinor, currency } = event.payload;
// event.meta always carries the tenant. You cannot forget to scope.
await recordRevenue(event.meta.tenantId, amountMinor, currency);
},
}
A handler that throws never breaks the emitter or the handlers after it — one broken integration cannot take down the platform. Async handlers are started but not awaited, so a slow subscriber never slows the thing that emitted.
White-label branding
Branding resolves down the tenant tree: platform defaults, then master partner, then partner, then business. An unset field inherits; an explicitly null field clears.
A partner’s primary colour overrides the anchor steps of the colour ramp while keeping the platform’s lightness curve, so contrast guarantees survive rebranding. Twenty-two fields are configurable, covering every surface a customer can see.