Authentication
Pre-release v1, published 2026-09-14. This page commits to the shape of the API, not to a
date. We will build exactly what is documented here. The shape can still change until
2026-10-14; after that, changes follow Versioning and stability.
The banner comes off one page at a time as each route goes live. While it is here, build against the contract and assume the route is not callable yet.
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.
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.
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 your ParsChat panel. 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
Three things live in your ParsChat panel rather than in this API:
The auth token is worth being precise about, because it points the opposite way to the key. Your API key authenticates you to us. The webhook auth token authenticates us to you: you choose the value, we store it, and we attach it to every event we deliver to your webhook URL — every chat and message event included. Your endpoint checks it and rejects anything without it. 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 auth token only affect your own infrastructure, so you own both — behind a panel login, which is a stronger credential than an API key.