Get started

Authentication

API keys for the Macaaw Public API: live and sandbox keys, the Authorization header, permissions and revoking.

Send your key in the Authorization header#

Every request carries an API key in the Authorization header with the API-Key scheme. Keys never go in the URL.

curl https://macaaw.com/public/v1/documents \
  -H "Authorization: API-Key mk_live_…"

The API is meant for server-to-server calls: it sets no cookies and does not answer browser cross-origin requests, so never put a key in front-end code or a mobile app.

Live and sandbox keys#

	Live key	Sandbox key
Looks like	`mk_live_ + 32 characters`	`mk_test_ + 32 characters`
Who can create one	Workspaces whose plan includes API access	Any signed-in user, on every plan
Documents	Real, legally binding signatures	Stamped “SANDBOX — NOT A VALID DOCUMENT”; recipients restricted (see Sandbox)
Plan limits	Count against the same monthly limits as the website	Never counted
Rate limit	Per endpoint group	10 requests per minute in total
Data	Kept like documents created on the website	Deleted after 7 days

Live and sandbox data never mix: a sandbox key only sees sandbox documents, tasks and webhook subscriptions, and a live key only sees live ones.

Create and manage keys#

Open Account → Developer → API keys.
Choose Create key, give it a name (for example the server or app it is for) and pick live or sandbox.
Copy the key. It is shown once: Macaaw stores only a hash and the last four characters.

The list shows each key's name, last four characters, who created it, when it was created and when it was last used. A workspace can have up to 10 active keys.

Treat keys like passwords. If one leaks, revoke it at once under API keys → Revoke — revoked keys stop working immediately — and create a new one.

Workspaces and permissions#

A key belongs to the workspace it was created in — your personal workspace or a team. Documents and tasks created with a team key belong to that team and show up in its account area. In a team, only the owner and admins can create or revoke keys, manage webhooks and see API logs. Creating and revoking keys is recorded in the audit log.

If your account is suspended, every key answers 403.

Authentication errors#

401 Unauthorized

{
  "type": "authentication_error",
  "code": "API_KEY_INVALID",
  "detail": "The API key is missing, not valid or has been revoked. Send Authorization: API-Key followed by your key."
}

Status	When
401	No `Authorization` header, an unknown or revoked key, or a malformed header.
401	`Authorization: Bearer …` — OAuth 2.0 is not available yet (code `OAUTH_NOT_SUPPORTED`).
403	Live key on a plan without API access (`API_ACCESS_REQUIRED`), or a suspended account.