# استفاده از دسترسی API

> برای اسکریپت‌ها و کلاینت‌های MCP توکن دسترسی شخصی بسازید و رویدادهای Livespace خود را با وب‌هوک‌ها به سیستم‌های خودتان بفرستید.

در تنظیمات › **دسترسی API**، توکن دسترسی شخصی می‌سازید تا یک اسکریپت یا کلاینت MCP بتواند از طرف شما از Dvina استفاده کند. مدیران نیز در همین بخش وب‌هوک اضافه می‌کنند تا رویدادهای Livespace را به سیستم‌های خودشان بفرستند.

دسترسی API در طرح Enterprise ارائه می‌شود. هر عضو می‌تواند توکن‌های خودش را بسازد؛ فقط مالکان و مدیران بخش **وب‌هوک‌ها** را می‌بینند.

## ساخت توکن

1. تنظیمات را باز کنید و **دسترسی API** را انتخاب کنید.
2. در بخش **توکن‌های دسترسی شخصی**، **ساخت توکن** را انتخاب کنید.
3. یک **نام** وارد کنید تا بعداً بدانید چه چیزی از آن استفاده می‌کند.
4. نوع **دسترسی** را انتخاب کنید: **فقط خواندن** یا **خواندن و نوشتن**.
5. زمان **انقضا** را انتخاب کنید: **پس از 30 روز**، **پس از 90 روز**، **پس از 365 روز** یا **بدون انقضا**.
6. **ساخت توکن** را انتخاب کنید.
7. در بخش **کپی توکن شما**، توکن را کپی کنید و در جای امنی نگه دارید. توکن فقط همین یک بار نمایش داده می‌شود.

توکن از طرف شما، در همان Livespace که آن را ساخته‌اید و با نقش فعلی شما در آنجا کار می‌کند. توکن **فقط خواندن** می‌تواند اطلاعات را بخواند، اما نمی‌تواند چیزی اضافه کند یا تغییر دهد.

برای استفاده از توکن در یک کلاینت MCP، [اتصال با کلید API به‌جای OAuth](/docs/dvina-mcp/overview#connect-with-an-api-key-instead-of-oauth) را ببینید.

## بررسی، تعویض یا لغو توکن

توکن‌های شما همراه با نوع دسترسی‌شان در بخش **توکن‌های دسترسی شخصی** فهرست می‌شوند. یکی را انتخاب کنید تا **شروع توکن**، نوع **دسترسی**، زمان **آخرین استفاده** و زمان **انقضا** را ببینید.

- **برای جایگزین کردن توکن**، **تعویض…** را انتخاب کنید، سپس برای تأیید **تعویض** را انتخاب کنید. توکن جدید جایگزین آن می‌شود و توکن قبلی بلافاصله از کار می‌افتد. توکن جدید را در بخش **کپی توکن شما** کپی کنید.
- **برای غیرفعال کردن توکن**، **لغو…** را انتخاب کنید، سپس برای تأیید **لغو** را انتخاب کنید. هر چیزی که از آن استفاده می‌کند بلافاصله از کار می‌افتد.

ساخت، تعویض و لغو توکن در [گزارش ممیزی](/docs/teams/audit-log) ثبت می‌شود.

## افزودن وب‌هوک

وب‌هوک رویدادهای Livespace را، که همان موارد ثبت‌شده در [گزارش ممیزی](/docs/teams/audit-log) هستند، به نشانی‌ای که انتخاب می‌کنید می‌فرستد.

1. در تنظیمات › **دسترسی API**، در بخش **وب‌هوک‌ها**، **افزودن وب‌هوک** را انتخاب کنید.
2. یک **نام** و **URL** وارد کنید. از یک URL عمومی با HTTPS استفاده کنید.
3. در بخش **رویدادها**، برای دریافت همهٔ رویدادها آن را خالی بگذارید، یا اقدام‌ها و حوزه‌ها را فهرست کنید؛ مانند `member.added` یا `sharing.*`.
4. **افزودن** را انتخاب کنید.
5. در بخش **کپی کلید محرمانهٔ امضا**، کلید محرمانه را کپی کنید. این کلید فقط همین یک بار نمایش داده می‌شود.

اگر Dvina پیام **این نشانی از Dvina قابل دسترسی نیست** را نمایش داد، از یک URL عمومی با HTTPS استفاده کنید.

### بررسی امضای هر درخواست

Dvina رویدادها را به‌صورت دسته‌ای و در قالب JSON می‌فرستد و هر درخواست را امضا می‌کند. با استفاده از کلید محرمانهٔ امضا بررسی کنید که درخواست از Dvina آمده باشد:

- هر درخواست یک هدر `X-Dvina-Signature` مانند `t=<timestamp>,v1=<signature>` دارد.
- امضا یک HMAC-SHA256 در قالب هگزادسیمال است که با کلید محرمانهٔ امضای شما، از برچسب زمانی، یک نقطه و بدنهٔ درخواست ساخته می‌شود.
- امضا را خودتان محاسبه و مقایسه کنید. درخواستی را که امضای آن مطابقت ندارد یا برچسب زمانی آن بیش از حد قدیمی است، رد کنید.

## بررسی یا تغییر وب‌هوک

وب‌هوک‌های شما در بخش **وب‌هوک‌ها** با وضعیتشان فهرست می‌شوند: **فعال**، **متوقف** یا **دچار خطا**. برای دیدن جزئیات، یکی را انتخاب کنید.

- **برای تغییر آن**، **نام**، **URL** یا **رویدادها** را ویرایش کنید، سپس **ذخیره** را انتخاب کنید.
- **برای توقف آن**، **ارسال رویدادها** را خاموش کنید. برای ازسرگیری ارسال، آن را دوباره روشن کنید.
- **برای بررسی عملکرد آن**، **وضعیت** و تعداد رویدادهای **ارسال‌شده** را بررسی کنید. وب‌هوکی که دچار خطا شده است، **آخرین خطا** را نشان می‌دهد. Dvina به تلاش ادامه می‌دهد و خطا را در گزارش حسابرسی ثبت می‌کند.
- **برای تغییر کلید محرمانهٔ آن**، **کلید محرمانهٔ امضای جدید…** را انتخاب کنید، سپس تأیید کنید. درخواست‌ها بلافاصله با کلید محرمانهٔ جدید امضا می‌شوند، پس دریافت‌کننده را فوراً به‌روزرسانی کنید.
- **برای حذف آن**، **حذف…** و سپس **حذف** را برای تأیید انتخاب کنید. دیگر چیزی به آن ارسال نمی‌شود.

## مطالب مرتبط

- [استفاده از Dvina در برنامه‌های دیگر با MCP](/docs/dvina-mcp/overview)
- [استفاده از گزارش حسابرسی](/docs/teams/audit-log)
- [نمای کلی تیم‌ها](/docs/teams/overview)