connections
POST /v1/connections/{provider}
Validate or store a provider access token.
احراز هویت
یک کلید API را به عنوان یک توکن حامل ارسال کنید. این کلید باید دارای مجوز connections.manage باشد؛ کلیدی که فاقد آن باشد با خطای 403 رد میشود، نه 404.
جایی که شناسه سازمان شما قرار میگیرد
این نقطه پایانی org_id را به عنوان یک پارامتر پرسوجو میپذیرد. آن را رها کنید تا فراخوانی کل زیردرخت اجارهای شما را پوشش دهد؛ آن را ارسال کنید تا فراخوانی به یک سازمان محدود شود.
شناسه سازمان شما در صفحه کلیدهای API در داشبوردتان، در کنار خود کلید قرار دارد. این شناسه در تمام درخواستهایی که ارسال میکنید یکسان است.
امتحان کنید
هر چیزی را که داخل براکتهای زاویهدار قرار دارد با مقادیر خودتان جایگزین کنید، و نگهدارنده کلید را با کلیدی از داشبورد خود جایگزین نمایید.
curl -X POST https://api.zinndigital.com/v1/connections/{provider} \
-H "Authorization: Bearer zdk_live_…"وارد شدهاید؟ کنسول API در داشبورد شما شناسه سازمان واقعی و کلید خودتان را پر میکند و درخواست را روی API زنده اجرا میکند تا بتوانید پاسخ واقعی را ببینید. این نقطه پایانی را در کنسول API باز کنید
جزئیات
With `validate_only` the token is checked and nothing is stored, and the result is returned with 200 **even when the token is invalid** — an invalid token is an answer the caller renders, not a request error. Without it the token is re-validated and then stored in Vault, returning 201; a token that fails validation is rejected with `TOKEN_INVALID` and never persisted. The token itself is never logged or echoed. Requires `connections.manage`.
پارامترها
| نام | نوع | الزامی | چیست |
|---|---|---|---|
provider (path) | ConnectionProvider | بله | The third-party provider whose connections are addressed. |
org_id (query) | Uuid | خیر | Which organization this connected account belongs to. Required when the caller manages connections for more than one — a reseller or an agency by construction — because a creden… |
Idempotency-Key (header) | string | خیر | Client-generated key that makes an unsafe request replay-safe: the server stores the first response and returns it verbatim for repeats. |
پاسخ
| نام | نوع | الزامی | چیست |
|---|---|---|---|
valid | boolean | بله | — |
account_login | object | بله | The account the token authenticates as, when valid. |
scopes | string[] | بله | — |
missing_scopes | string[] | بله | Required scopes the token lacks. Empty when the token is valid, and also empty when the provider could not enumerate its permissions — in that case the connection is usable but… |
message | object | بله | Human-readable explanation, or null when valid. |
permissions | PermissionReport | null | خیر | The per-permission checklist, exercised against the provider. ⛔ `null` means **we cannot test this provider's permissions** — it does not mean "nothing is required". The two rea… |
خطاهایی که این نقطه پایانی میتواند برگرداند
401 · 403 · 422 · 429 · 503