API keys and scopes
Every request uses a bearer API key. Organization-scoped requests also identify the craftivo organization they act on.
Send the bearer key
Add the key to the Authorization header. Keys are secrets and must only be used from trusted server-side environments.
Authorization: Bearer msk_…
X-Organization-Id: org_…Select an organization
Start with GET /api/v1/me. It works without an organization header and lists the organizations available to the key. For all other calls, send the selected ID as X-Organization-Id whenever required.
New keys created in organization settings are bound to that organization. A different organization ID is rejected with HTTP 403 instead of accessing data from another business.
Choose the narrowest scope
read
Allows GET requests. Use it for reporting, exports, search, and one-way syncs.
read_write
Allows reads plus supported POST, PUT, PATCH, and DELETE operations.
Webhook subscription endpoints accept both scopes so a read-only integration can manage its own subscriptions. Other write attempts with a read-only key return HTTP 403 withinsufficient_scope.
Rotate or revoke a key
Create a replacement key, update the integration, verify a request, then revoke the old key in organization settings. Revocation takes effect for subsequent requests. The full value of an existing key cannot be retrieved again.