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

# احراز هویت

> یک کلید برای همه ربات‌ها. کلیدها چطور صادر می‌شوند، به چه چیزهایی دسترسی دارند و عمداً به چه چیزهایی ندارند.

> **Warning**
>
> **نسخه پیش‌انتشار `v1`، منتشرشده در ۲۰۲۶-۰۹-۱۴.** این صفحه به شکل API متعهد است، نه به تاریخ
> آن. دقیقاً همان چیزی را می‌سازیم که اینجا مستند شده است. شکل API تا
> **۲۰۲۶-۱۰-۱۴** هنوز ممکن است تغییر کند؛ پس از آن، تغییرات از [نسخه‌بندی و پایداری](/documentation/reference/versioning-stability) پیروی می‌کنند.
>
> این بنر صفحه‌به‌صفحه و هم‌زمان با فعال‌شدن هر مسیر برداشته می‌شود. تا وقتی بنر هست، بر اساس
> قرارداد پیاده‌سازی کنید و فرض کنید آن مسیر هنوز قابل فراخوانی نیست.

هر درخواست کلید شما را به‌صورت توکن `Bearer` همراه دارد.

```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();
```

کلید API شما محرمانه است. آن را با کسی به اشتراک نگذارید و در کد سمت کلاینت قرار ندهید.

## یک کلید برای همه ربات‌ها

برای هر حساب یک کلید دارید که همه ربات‌های شما را پوشش می‌دهد. کلید جداگانه برای هر ربات یا هر
مشتری وجود ندارد.

|                       |                               |
| --------------------- | ----------------------------- |
| از کجا می‌گیرید       | از پنل پارس‌چت کپی می‌کنید    |
| همراه با              | بسته‌ای که دسترسی به API دارد |
| نمایش                 | فقط یک بار، هنگام ساخت        |
| آنچه ما ذخیره می‌کنیم | فقط یک HMAC                   |
| انقضا                 | خودتان در پنل تعیین می‌کنید   |

> **Warning**
>
> کلید گم‌شده بازیابی نمی‌شود و باید تعویض شود. چون فقط یک HMAC از آن ذخیره می‌کنیم، نمی‌توانیم
> کلید را دوباره نشان‌تان دهیم. به‌محض دریافت، آن را در ابزار مدیریت اسرار (secret manager) خود بگذارید.

## کلید چه کاری می‌تواند بکند و چه کاری نمی‌تواند

کلید فقط درون حساب شما عمل می‌کند. نمی‌تواند مقصد داده‌های شما را تغییر دهد.

|                                 | با کلید شما |     فقط از پنل    |
| ------------------------------- | :---------: | :---------------: |
| ساخت و حذف ربات                 |      ✅      |                   |
| اتصال و قطع کانال               |      ✅      |                   |
| فعال و غیرفعال‌کردن کانال       |      ✅      |                   |
| پاسخ به گفتگوها و بارگذاری فایل |      ✅      |                   |
| مدیریت قانون‌های خودکارسازی     |      ✅      |                   |
| خواندن مصرف                     |      ✅      |                   |
| خواندن تنظیمات وب‌هوک           |      ✅      |                   |
| **تغییر** آدرس وب‌هوک           |             |         🔒        |
| تنظیم توکن احراز هویت وب‌هوک    |             |         🔒        |
| تعیین انقضای کلید               |             |         🔒        |
| ساخت یا تعویض کلید              |             |         🔒        |
| **تغییر** آدرس بازگشت           |             | با ما تماس بگیرید |

هدف همین تفکیک است. اگر کلیدتان لو برود، مهاجم می‌تواند درون حساب شما بخواند و عمل کند، و باید
فوراً کلید را تعویض کنید. اما نمی‌تواند جریان رویدادهای شما را به اندپوینتی از آن خودش هدایت کند،
چون این کار ورود به پنل را لازم دارد که اعتبارنامه‌ای متفاوت و قوی‌تر است.

## دسترسی از نقش می‌آید

ساخت ربات و دسترسی به اینستاگرام ویژگی کلید نیستند. این دسترسی‌ها روی حساب شما اعطا می‌شوند و در
هر درخواست بررسی می‌شوند. برای گرفتن هر کدام، با تیم فروش ما تماس بگیرید.

بنابراین دسترسی را می‌توان بدون دست‌زدن به کلید شما اعطا یا لغو کرد. با تغییر قرارداد، لازم نیست
یکپارچه‌سازی را از نو انجام دهید.

> **Info**
>
> `403` در فراخوانی‌ای که باید کار کند، معمولاً یعنی نقشی کم است. `401` به خود کلید مربوط است:
> اشتباه، باطل‌شده یا منقضی.

## دو آدرس، و کاربرد هر کدام

|                 | چیست                                                                      | جهت               |
| --------------- | ------------------------------------------------------------------------- | ----------------- |
| **آدرس وب‌هوک** | اندپوینت شما که رویدادها را دریافت می‌کند                                 | ما ← سرور شما     |
| **آدرس بازگشت** | صفحه‌ای از شما که مرورگر مشتری پس از تأیید دسترسی اینستاگرام به آن می‌رسد | مرورگر ← سایت شما |

**آدرس وب‌هوک** را خودتان در پنل پارس‌چت تنظیم می‌کنید. هیچ API برای آن وجود ندارد: اندپوینتی که
بتواند آن را بنویسد، یک کلید دزدیده‌شده را به راهی برای منحرف‌کردن کل جریان رویدادهای شما تبدیل می‌کرد.

**آدرس بازگشت** تنها چیزی است که به ما می‌دهید. آن را برای رابط پارس‌چت خود بفرستید تا ما
تنظیمش کنیم.

این دو، دو چیز متفاوت‌اند و هر دو لازم‌اند. آدرس وب‌هوک ارتباط سرور به سرور است. آدرس بازگشت
جایی است که مرورگر یک مشتری واقعی در میانه ثبت‌نام به آن می‌رود.

> **Warning**
>
> پیش از اولین اتصال اینستاگرام، آدرس بازگشت‌تان را به ما اطلاع دهید. اگر تنظیم نشده باشد، فرایند
> تأیید مشتری شما را به داشبورد ما می‌فرستد: صفحه‌ای که هرگز ندیده، در محصولی که فکر می‌کند مال شماست.

## آنچه در پنل تنظیم می‌کنید

سه چیز به‌جای این API در پنل پارس‌چت شما قرار دارد:

|                            |                                                                                                 |
| -------------------------- | ----------------------------------------------------------------------------------------------- |
| **کلید API**               | هنگام ساخت، آن را کپی کنید. انقضایش را تعیین کنید و هر وقت لازم بود تعویضش کنید                 |
| **آدرس وب‌هوک**            | جایی که رویدادهای شما را با POST به آن می‌فرستیم                                                |
| **توکن احراز هویت وب‌هوک** | اعتبارنامه‌ای که **ما برای شما می‌فرستیم**، تا اندپوینت شما بتواند ثابت کند درخواست از طرف ماست |

دقت درباره توکن احراز هویت ارزشش را دارد، چون جهتش برعکس کلید است. کلید API **شما را نزد ما**
احراز هویت می‌کند. توکن احراز هویت وب‌هوک **ما را نزد شما** احراز هویت می‌کند: شما مقدارش را انتخاب
می‌کنید، ما ذخیره‌اش می‌کنیم و آن را به هر رویدادی که به آدرس وب‌هوک شما تحویل می‌دهیم پیوست
می‌کنیم — از جمله همه رویدادهای گفتگو و پیام. اندپوینت شما آن را بررسی می‌کند و هر درخواستی را که
آن را نداشته باشد رد می‌کند.
[رویدادهای وب‌هوک](/documentation/guides/webhook-events#if-your-endpoint-needs-its-own-authentication) را ببینید.

### چرا این تفاوت

آدرس بازگشت تعیین می‌کند مرورگر یک شخص به کجا فرستاده شود، پس اندپوینتی که بتواند آن را بنویسد،
یک کلید دزدیده‌شده را به ابزاری برای ریدایرکت باز و فیشینگ تبدیل می‌کرد. آدرس وب‌هوک و توکن
احراز هویت فقط روی زیرساخت خود شما اثر دارند، پس هر دو در اختیار شماست — پشت ورود به پنل، که
اعتبارنامه‌ای قوی‌تر از کلید API است.