In short
Your own software can do what the Reseller menu does — and work inside every client workspace. You make two keys in Reseller › Settings: a reseller key for client workspaces, messages, conversations, contacts and the rest, and a publishing key for posts. Inside one client workspace, your software sends its ID in the X-Workspace-Id header. Every endpoint is at miragechat.io/developers/reseller.
Before you start
- A reseller account, and you are its owner or an admin — become a partner.
- Someone to put the keys into your software — a developer, or your platform’s settings.
- For the webhook: your server’s public address, starting with https://.
1. Make your two keys
Open Settings
Go to
Resellerand open the Settings tab. The card Use the API holds both keys.Make the reseller key
Press Create reseller key. It is shown once — Your reseller key — shown once, keep it safe. Press Copy and keep it in your software’s settings, never in an email or a chat.
Tick the confirmation
Under it, tick “Posts sent with this key are published on the selected accounts in my name.” The publishing key is made in your name.
Make the publishing key
Press Create publishing key and copy it the same way: Your publishing key — shown once, keep it safe.
| Key | What it does |
|---|---|
| Reseller key | Creates and closes client workspaces, makes connect links, adds their people, reads your statement and paid channels — and, inside any client workspace, sends messages and reads and changes conversations, contacts, webhooks, the team, automations, WhatsApp forms, calls and analytics. It never posts. |
| Publishing key | Posts to the Instagram, Facebook and TikTok accounts of the client workspace you name — every one of them, including accounts connected later — and finds TikTok sounds for them (GET /music, GET /music/{id}/videos, the trending videos that use a sound; how). It reads no conversations. |
Both keys are listed in Reseller › Settings under Your keys, and in Security › Developer. Revoke a key you no longer need in either place; it stops at once.
2. Work inside a client workspace
Your software sends the client workspace’s ID in the X-Workspace-Id header, with either key. Everything the request does is then that workspace’s: its channels, conversations, contacts, webhooks and posts. Without the header, the key works in your own workspace.
The ID is shown under each name in Reseller › Client workspaces, and GET /reseller/workspaces lists them all.
| Your software sends | What happens |
|---|---|
X-Workspace-Id: 1304 with the reseller key | It acts as client workspace 1304 — for example, POST /messages answers one of its customers. |
X-Workspace-Id: 1304 with the publishing key | POST /posts posts to that workspace’s Instagram, Facebook and TikTok accounts. |
| An ID that is not one of yours | 404 workspace_not_found — never another reseller’s workspace. |
3. Create a client workspace and its link
POST /reseller/workspaces with a name — and, if you like, its timezone, your own reference in external_id and a return_url. With a return_url, the answer also carries connect_url: the page with your name and logo where your client connects WhatsApp, Instagram and a Facebook Page. It works for 24 hours.
- A new link —
POST /reseller/workspaces/{id}/connect-link, valid for 1 to 168hours. - Take the links back —
POST /reseller/workspaces/{id}/connect-link/revoke: every open link of that workspace stops at once. - Your client’s people —
POST /reseller/workspaces/{id}/userswith an email, a password you set and the roleadminoragent;PATCH …/users/{userId}renames them, changes the role or password, or switches them off. We email them no invitation. - Close it —
DELETE /reseller/workspaces/{id}: read-only at once, its channels switched off, its data kept for 90 days.
4. One webhook for every client
Paste your address
In
Reseller › Settings, under Webhook for all your client workspaces, paste your server’s https:// address.Add it
Press Add webhook. The Webhook signing secret is shown once: copy it into your server, which checks every delivery with it.
It receives six events of every client workspace — message.received, message.sent, conversation.created, conversation.closed, account.connected and account.disconnected — each with the workspace_id it came from, and signed in the X-Mirage-Signature header.
Your software can make the same webhook itself: POST /webhooks with include_clients: true and the events you choose, sent with the reseller key and without X-Workspace-Id. If it takes the post.* events, the posts of your client workspaces arrive there too.
5. Your statement and channels by API
| Call | What it answers |
|---|---|
GET /reseller/me | Your balance, your prices, what a month costs at today’s channels, and what falls due in the next 7 days. |
GET /reseller/statement | Every charge, newest first — the lines of the Statement tab. |
GET /reseller/channels | Every paid channel of your client workspaces, with the date it is paid until and its price a month — to bill your own clients by. |
What the API does not do
- YouTube. YouTube’s rules for apps do not allow its data through another app’s API. Your clients post to YouTube from Instant Post, inside their workspace.
- AI replies in a client workspace. Client workspaces have no AI assistant, so
POST /ai/replyis refused there. - Prices and your partner account. Our team sets your prices and switches your account on.
- Connecting channels. The connect link covers WhatsApp, Instagram and a Facebook Page; Telegram, website chat, SMS, TikTok and YouTube are connected inside the client workspace, under
Channels.
If something looks wrong
“X-Workspace-Id works only with a key that has the reseller scope. …”
The key is not one of the two made in Reseller › Settings. Use the reseller key — or the publishing key, for posts.
“There is no client workspace with this id among yours.”
The ID is not one of your client workspaces. Check it under the name in Client workspaces, or with GET /reseller/workspaces.
“This key can only read. Create a key with the publish scope to post.”
Posts need the publishing key. The reseller key sends messages; it never posts.
“This key is a Publishing API key and cannot use the messaging API. …”
Messages, conversations and contacts need the reseller key. The publishing key only posts.
“The person who confirmed this key is no longer on the team. …”
The publishing key was made in the name of someone who has left. Make a new one in Reseller › Settings.
A change answers 402 with code on_hold
A renewal of yours was not paid, so your account and your client workspaces are paused: reading still works, sending and changing are refused. Add money under Billing — when a renewal isn’t paid.
On your phone
The keys and the webhook are made on the web, under Reseller › Settings. Your software then calls the API from its own server.
Ready?
Opens MirageCHAT in this tab. Sign in first if you’re not already.
Did this guide help?
Related guides
Product guide: API, webhooks and integrations
Still stuck? Write to info@miragechat.io with your workspace name. Never send passwords or codes.