> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs-parschat.parstechai.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-parschat.parstechai.com/_mcp/server.

# Authentication

> One key, all your robots. How to create it in the panel, what it reaches, and what it deliberately cannot.

Every request carries your key as a bearer token.

```http
Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxx
```

**`cURL`**

```bash cURL
curl https://api-chat.parstechai.com/v1/robots \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxx"
```

**`Python`**

```python Python
import requests

robots = requests.get(
    "https://api-chat.parstechai.com/v1/robots",
    headers={"Authorization": f"Bearer {API_KEY}"},
    timeout=10,
).json()
```

**`Node.js`**

```javascript Node.js
const res = await fetch("https://api-chat.parstechai.com/v1/robots", {
  headers: { Authorization: `Bearer ${API_KEY}` },
});
const robots = await res.json();
```

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.

|                  |                                                                                |
| ---------------- | ------------------------------------------------------------------------------ |
| Where you get it | You create it yourself in the panel: see [Get your API key](#get-your-api-key) |
| Comes with       | A plan that includes API access, or an active free trial                       |
| Shown            | Once, at creation                                                              |
| Stored by us     | An HMAC only                                                                   |
| Expiry           | You choose 1, 3, 6 or 12 months when you create it                             |

> **Warning**
>
> 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.

#### Sign in

Go to [chat.parstechai.com](https://chat.parstechai.com) and sign in with the account that owns
your robots.

#### 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**.

![The profile menu, open, with Profile, Contact Support and Exit](/_fern-files/_img/3087be5b56cae3b5dd134f565f5be7efd95ed41b50726dc6a79b54a8253677da.webp)

#### Open Access keys & webhook

Open the **Access keys & webhook** tab. Before you have a key, the table is empty.

![The Access keys & webhook tab, with the Create API key button](/_fern-files/_img/6b67f72c70677fda957b85945120d39a651c1e88114da25e76620120993e1490.webp)

#### 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 Create API key dialog with the validity selector](/_fern-files/_img/a255b1797819498053ed86b365beb4a082c582fd1514b5c58313e2afaed69864.webp)

#### Copy the key now

The key appears once, in the form `pk_live_` followed by random characters. Click **Copy key**,
store it in your secret manager, and only then click **I copied and saved the key**. When you
close this window the key cannot be shown again.

![The new key shown once, with a Copy key button](/_fern-files/_img/6bce3cb96790084f66506f0c80b8e0ccbb039fcf73e5eb3d41a5685dddea318a.webp)

#### Check the table

The key now appears in the table with its service name, a preview such as `pk_live_••••x7Kq`,
its creation and expiry dates, and its status.

![The key table with one active key and a delete icon](/_fern-files/_img/1861faa0700d406d4af816aadc60cca92bad09b16143f0d5d557ed2a31b60bf4.webp)

The images show a placeholder key. Your own key is different, and you should never share it.

> **Note**
>
> **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.

1. 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`.
2. Click **Create API key** again and copy the new key as above.
3. 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.

![The Edit webhook dialog with the webhook address and Deliver events toggle](/_fern-files/_img/5afd4281507f147750b4843f8683eb2e49ffba284454ba3d1d90f0e2c7fcb572.webp)

1. Click **Set address** (or **Edit webhook** once an address exists).
2. Enter your **Webhook address**. We send events to it as `POST` requests, so it must be a public
   address.
3. Optionally, turn **Deliver events** off to pause deliveries. Turn it back on to resume.
4. 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](/documentation/guides/webhook-events#if-your-endpoint-needs-its-own-authentication).
5. 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.

|                                                     | With your key | Panel only |
| --------------------------------------------------- | :-----------: | :--------: |
| Create and delete robots                            |       ✅       |            |
| Connect and disconnect channels                     |       ✅       |            |
| Enable and disable channels                         |       ✅       |            |
| Reply to conversations and upload files             |       ✅       |            |
| Manage automation rules                             |       ✅       |            |
| Read usage                                          |       ✅       |            |
| Read your webhook configuration                     |       ✅       |            |
| **Change** the webhook URL                          |               |     🔒     |
| Set the custom webhook headers                      |               |     🔒     |
| Create, revoke or rotate a key (and set its expiry) |               |     🔒     |
| **Change** the return URL                           |               | contact us |

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.

> **Info**
>
> 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

|                 | What it is                                                          | Direction           |
| --------------- | ------------------------------------------------------------------- | ------------------- |
| **Webhook URL** | Your endpoint that receives events                                  | us → your server    |
| **Return URL**  | Your page a customer's browser lands on after authorising Instagram | browser → your site |

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.

> **Warning**
>
> 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:

|                            |                                                                                                            |
| -------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **API key**                | Create it, copy it once, and revoke it to rotate. You choose its expiry                                    |
| **Webhook URL**            | Where we POST your events                                                                                  |
| **Custom headers**         | Headers **we send to you** with every event, so your endpoint or gateway can recognise the request as ours |
| **Webhook signing secret** | Shown once when you first save the webhook. Use it to verify `X-ParsChat-Signature`                        |

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](/documentation/guides/webhook-events#if-your-endpoint-needs-its-own-authentication).

### 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.