احراز هویت
یک کلید API را به عنوان یک توکن برbearer ارسال کنید. این نقطه پایانی مجوز خاصی را در مشخصات خود ذکر نمیکند، بنابراین به جای فرض کردن، حداقل نیازهای کلید خود را بدهید و پاسخ را بررسی کنید.
این نقطه پایانی هیچ شناسه سازمانی را دریافت نمیکند. کلید شما در حال حاضر سازمان مربوطه را مشخص میکند و پاسخ در همان محدوده ارائه میشود.
امتحان کنید
هر چیزی را که داخل براکتهای زاویهدار قرار دارد با مقادیر خودتان جایگزین کنید، و نگهدارنده کلید را با کلیدی از داشبورد خود جایگزین نمایید.
curl -X POST https://api.zinndigital.com/v1/sites/{siteId}/collaborators \
-H "Authorization: Bearer zdk_live_…" \
-H "Content-Type: application/json" \
-d '{ "email": <string>, "role": <SiteCollaboratorRole>, "reason": <string> }'وارد شدهاید؟ کنسول API در داشبورد شما شناسه سازمان واقعی و کلید خودتان را پر میکند و درخواست را روی API زنده اجرا میکند تا بتوانید پاسخ واقعی را ببینید. این نقطه پایانی را در کنسول API باز کنید
جزئیات
Grants one person access to this one site at one role, optionally until a date, and gives them the narrow `site_collaborator` organisation membership if they have none. The narrowing is enforced by Postgres row-level security on the site table itself, not by a filter in a query, so it applies to every endpoint on this API rather than to the ones somebody remembered. ⭐ **The person need not have an account yet.** An address nobody has signed in as is invited in the same call: an ordinary organisation invitation is sent at the `site_collaborator` role, and the grant is returned with `status: pending` and a null `user_id`. The moment they accept — which proves control of that inbox through the identity provider, so no id is ever guessed — the grant activates for that person. A pending grant narrows nobody: nothing is reachable until the accept. If the address already holds a pending invitation to the *whole* organisation the call is refused with `SITE_COLLABORATOR_ALREADY_INVITED` rather than quietly downgrading that invitation to one site. **What a collaborator may then do is the per-site role, on that site only.** A request whose path names a granted site is evaluated with the role's keys (`viewer` reads; `editor` adds `hosting.deploy.manage`, `sites.cache.purge`, `hosting.performance.manage`, `sites.wp_login`, `sites.panel_access`, `sites.restart`, `hosting.php.manage`; `manager` adds `hosting.backup.manage`, `hosting.ssl.manage`, `hosting.cdn.manage`, `hosting.applications.manage`, `hosting.import.manage`). A request naming any other site answers `404`, and a request naming no site — the collection endpoints and every organisation-level surface such as members, API keys and billing — carries only `sites.view`, so it is refused with `403`. Revoking a grant takes effect on the next request, whatever token the person is holding. Every refusal carries its OWN `error.code`, because the status says what happened and only the code says what to do about it. `409` is about the world: `SITE_COLLABORATOR_ALREADY_GRANTED` (this person already has a live or pending grant here), `SITE_COLLABORATOR_ALREADY_A_MEMBER` (they are already an unrestricted member, so a grant would imply a restriction we are not applying — a lie in an access table) and `SITE_COLLABORATOR_ALREADY_INVITED` (above). `422` is about the request: `SITE_COLLABORATOR_EXPIRY_IN_THE_PAST` and `SITE_COLLABORATOR_REASON_REQUIRED`. ⛔ Key on the code, never on `error.message`. The message is a sentence written for a person and it is translated; the code is the contract.
پارامترها
| نام | نوع | الزامی | چیست |
|---|---|---|---|
siteId (path) | Uuid | بله | Site ID (UUIDv7). |
بدنه درخواست
| نام | نوع | الزامی | چیست |
|---|---|---|---|
email | string | بله | The person to share with. An address with no account here is invited in the same call and the grant is returned `pending` — see the endpoint description. |
role | SiteCollaboratorRole | بله | What a collaborator may do on the site they were granted. `viewer` reads it; `editor` adds the day-to-day work (deploys, cache, plugins, staging); `manager` adds the structural… |
reason | string | بله | Why they are being given this site. Required rather than optional: an optional reason is one nobody fills in, and the audit value of the record collapses to *"somebody granted s… |
expires_at | object | خیر | Optional automatic end. Null means until revoked. A time in the past is refused with `expiry_in_the_past` rather than silently creating a dead grant. |
پاسخ
| نام | نوع | الزامی | چیست |
|---|---|---|---|
id | string | بله | — |
site_id | string | بله | — |
user_id | object | بله | The collaborator, once known. Null while the grant is `pending` — the address has been invited and nobody has signed in as it yet. |
email | string | بله | — |
role | SiteCollaboratorRole | بله | What a collaborator may do on the site they were granted. `viewer` reads it; `editor` adds the day-to-day work (deploys, cache, plugins, staging); `manager` adds the structural… |
reason | string | بله | Why this person was given this site. Required on creation, and returned here because a year later it is the only thing that can answer *"why does this person have my site?"*. |
granted_by | string | بله | The audit ref of whoever granted it, `user:<id>`. |
created_at | string | بله | — |
expires_at | object | بله | When the grant lapses on its own, or null for *until revoked*. Evaluated at read time, so it takes effect on the clock rather than when a sweep next runs. |
active | boolean | بله | Neither revoked nor past its expiry, as of this response. |
status | string<pending, active, expired, revoked> | بله | `pending` — invited, waiting for the person to sign in as that address; `active` — in force now; `expired` — lapsed on its own end date; `revoked` — ended by the owner, the row… |
خطاهایی که این نقطه پایانی میتواند برگرداند
401 · 403 · 404 · 409 · 422 · 429