connections
POST /v1/connections/{provider}
Validate or store a provider access token.
Authentication
Send an API key as a bearer token. The key must carry the connections.manage permission; a key without it is refused with 403, not 404.
Where your organisation id goes
This endpoint takes org_id as a query parameter. Leave it out and the call covers your whole tenancy subtree; send it to narrow the call to one organisation.
Your organisation id is on the API keys screen in your dashboard, beside the key itself. It is the same id in every call you make.
Try it
Replace anything in angle brackets with your own values, and the key placeholder with a key from your dashboard.
curl -X POST https://api.zinndigital.com/v1/connections/{provider} \
-H "Authorization: Bearer zdk_live_…"Signed in? The API console in your dashboard fills in your real organisation id and your own key, and runs the request against the live API so you can see the actual response. Open this endpoint in the API console
Details
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`.
Parameters
| Name | Type | Required | What it is |
|---|---|---|---|
provider (path) | ConnectionProvider | Yes | The third-party provider whose connections are addressed. |
org_id (query) | Uuid | No | 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 | No | Client-generated key that makes an unsafe request replay-safe: the server stores the first response and returns it verbatim for repeats. |
Response
| Name | Type | Required | What it is |
|---|---|---|---|
valid | boolean | Yes | — |
account_login | object | Yes | The account the token authenticates as, when valid. |
scopes | string[] | Yes | — |
missing_scopes | string[] | Yes | 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 | Yes | Human-readable explanation, or null when valid. |
permissions | PermissionReport | null | No | 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… |
Errors this endpoint can return
401 · 403 · 422 · 429 · 503