Management API
How to call the management API, page through its lists, retry its POSTs safely and read its errors.
The management API manages an org: its brands, apps, APIs, users, members, roles, invites, webhooks, API keys and audit log. Every route is under https://api.synq.build/v1.
Authentication
Send Authorization: Bearer <credential>, where the credential is either:
- an org API key (
sk_live_…orsk_test_…), made with the API keys routes, or - an access token for the management API from Synq's own issuer,
https://accounts.synq.build, for a person who is a member of the org.
Each route needs one permission. An API key has the permissions it was made with; a member has their role's.
Lists
Every list takes ?limit= (50 by default, 200 at the most) and ?cursor=, and answers { data, next_cursor }. Pass next_cursor back as cursor for the next page until it is null. A cursor is opaque: don't build or parse one.
Retrying a POST
Send an Idempotency-Key header with a POST, and a retry with the same key and the same request gets the first response back (with Idempotent-Replayed: true) without anything happening twice. Responses are kept for 24 hours. The same key with another request is refused (idempotency_key_conflict), and so is a second request while the first still runs (idempotency_key_in_flight). An error isn't kept, so a failed request can be retried as it is.
Errors
Errors are problem documents (RFC 9457) with a stable code: see every error code. A rate limit answers rate_limited with a Retry-After header.