Provisioning API

For another product (such as Tally) to create WhatsApp apps for its own customers and let them pair by QR inside that product.

Header: x-provisioning-key: <key>. A key can create apps and manage only the ones it created. Any other app answers 404, so a key can never list, read or delete apps it did not create. Prefer this over x-admin-key in products.

Step-by-step

This page is the reference. For the full flow with code (create, QR, webhooks, lifecycle), read Provisioning apps from your product.

Get a key

An operator creates it (shown once):

node scripts/create-provisioner.js "Tally" 200     # name, optional app limit
# or POST /api/provisioners {"name":"Tally","maxApps":200} with x-admin-key

Endpoints

Method	Path	Body	Notes
POST	/api/provision/apps	{ name, webhookUrl?, externalRef? }	201 with apiKey and webhookSecret, returned only here. Pairing starts straight away.
GET	/api/provision/apps	?externalRef=	{ "apps": [...] }, this key's apps with live status.
GET	/api/provision/apps/:id
PATCH	/api/provision/apps/:id	{ name?, webhookUrl? }
GET	/api/provision/apps/:id/qr		{ status, qr }, same as the tenant /api/qr.
POST	/api/provision/apps/:id/pairing-code	{ phoneNumber }	Link with a phone number instead of scanning.
POST	/api/provision/apps/:id/webhook-secret		New secret, returned only here.
POST	/api/provision/apps/:id/unlink		Log out and show a fresh QR.
DELETE	/api/provision/apps/:id		Stops the client and deletes the app, session and messages.

externalRef is your own id for the customer. Use it to find their app again with GET /api/provision/apps?externalRef=....

Typical flow

1. Your backend calls POST /api/provision/apps for a new customer and stores id, apiKey and webhookSecret.
2. Your UI polls GET /api/provision/apps/:id/qr and shows the QR image until status is ready.
3. From then on, your backend sends with the app's own apiKey through the Tenant API and receives webhooks.

Limits

Each app runs its own WhatsApp browser, so a key holds at most maxApps apps (409 APP_LIMIT; default PROVISION_MAX_APPS, 100) and may create at most PROVISION_CREATES_PER_HOUR per hour (default 30; over that is 429 with Retry-After). Revoking a key stops it at once while its apps keep running.