Authentication
Every request carries your key as a bearer token.
Remember that your API key is a secret. Do not share it or expose it in client-side code.
One key, all your robots
You get one key per account, and it spans every robot you own. There is no per-robot key and no per-customer key.
A lost key is rotated, not recovered. Because we store only an HMAC, we cannot show you the key again. Put it in your secret manager the moment you receive it.
Get your API key
You create the key yourself, in the ParsChat panel. It takes a minute.
Open your account
Click the profile icon at the end of the top bar (top-left in the Persian panel, top-right in English) and choose Profile.
Open Access keys & webhook
Open the Access keys & webhook tab. Before you have a key, the table is empty.
Create the key
Click Create API key, choose how long the key stays valid (1, 3, 6 or 12 months) and click Confirm and generate key.
The images show a placeholder key. Your own key is different, and you should never share it.
Who can create a key. Key creation needs a plan that includes API access, or an active free
trial. During a free trial the key works for the robot, usage and webhook endpoints; the
Instagram endpoints need an Instagram API plan. If neither applies, the panel says “API access
has not been enabled for your account” and Create API key stays disabled. When a free trial
ends without such a plan, the key answers 403.
Rotate or revoke a key
An account holds one key, so Create API key is disabled while a key exists.
- In the key’s row, click the delete icon and confirm with Delete. The key stops working
immediately, and every integration that uses it receives
401. - Click Create API key again and copy the new key as above.
- Put the new key into your integration.
Do this when a key leaks, when it is about to expire, or when someone who knew it leaves your team.
Set your webhook
On the same tab, Webhook delivery shows the address that receives your events, with a copy button.
- Click Set address (or Edit webhook once an address exists).
- Enter your Webhook address. We send events to it as
POSTrequests, so it must be a public address. - Optionally, turn Deliver events off to pause deliveries. Turn it back on to resume.
- Optionally, click Add header to add Custom headers that we attach to every delivery. Header values are never shown again after you save. When you save headers, the list you enter replaces all current headers, so enter every header’s value. See Webhook events.
- Click Save.
The first time you save, the panel shows your Webhook signing secret once. Copy it: you use it
to verify the X-ParsChat-Signature header on every delivery. To replace it later, turn on
Generate a new signing secret when you edit the webhook. The old secret stops working at once.
Setting the webhook also needs API access, as for the key.
What a key can and cannot do
A key acts inside your account. It cannot change where your data goes.
That split is the point. If your key leaks, the attacker can read and act inside your account, and you should rotate immediately. They cannot redirect your event stream to an endpoint of their own, because that requires a panel login, which is a different and stronger credential. In the table, 🔒 means you do it in the panel: Profile → Access keys & webhook.
Access comes from a role
Robot creation and Instagram access are not properties of the key. They are granted on your account and checked on every request. To get access to either, contact our sales team.
Access can therefore be granted or revoked without touching your key. You do not re-integrate when your contract changes.
A 403 on a call that should work is usually a missing role. A 401 is the key itself: wrong,
revoked, or expired.
Two URLs, and what each is for
You set the webhook URL yourself, in the panel under Profile → Access keys & webhook. There is no API for it: a writable endpoint would turn a stolen key into a way to redirect your entire event stream.
The return URL is the one thing you give us. Send it to your ParsChat contact and we configure it.
They are different things and both are needed. The webhook URL is server-to-server. The return URL is where a real customer’s browser goes mid-signup.
Tell us your return URL before your first Instagram connection. Without one configured, the handshake sends your customer to our dashboard: a screen they have never seen, on a product they believe is yours.
What you set in the panel
Four things live in your ParsChat panel, under Profile → Access keys & webhook, rather than in this API:
Custom headers are worth being precise about, because they point the opposite way to the key. Your API key authenticates you to us. Custom headers authenticate us to you: you choose the values, we store them, and we attach them to every event we deliver to your webhook URL, every chat and message event included. Your endpoint checks them and rejects anything without them. See Webhook events.
Why the difference
The return URL decides where a person’s browser is sent, so a writable endpoint would turn a stolen key into an open-redirect and phishing tool. The webhook URL and the custom headers only affect your own infrastructure, so you own both, behind a panel login, which is a stronger credential than an API key.