Agent-readable docs index: /docs/llms.txt. Full docs in one file: /docs/llms-full.txt. Download /docs/docs.zip to grep all markdown files locally.

Authenticate API requests with scoped keys

Customer endpoints use Bearer API keys issued inside Convert. A key identifies its workspace and allowed scopes. Send it in the Authorization header over HTTPS, never as a query parameter.
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Create and retain a key

Open Account → API keys, choose a descriptive name, select required scopes and the offered expiry settings, and copy the full key once. Convert stores a SHA-256 digest rather than the raw key; returning to the settings page does not recover the original secret.
Store the key server-side in your application's secret manager or environment configuration. Use separate named keys for independent integrations so rotation and revocation are manageable.

Available scopes

  • messages:write: single-message requests, batch creation, and batch status.
  • contacts:write: contact creation/update/delete, list-specific upsert, and identify.
  • campaigns:read: campaign list and detail.
  • segments:read: segment retrieval and read-oriented status/history.
  • segments:write: segment draft, preview/evaluation, publishing, and archival actions.
  • sender_ids:read / sender_ids:write: query or submit Sender ID requests.
  • events:write: report contact events.
  • automations:write: invoke an active API-triggered automation.
Grant the minimum scope set the application actually needs. Existing restricted keys do not automatically gain a newly introduced scope.

Expiry, revocation and isolation

Missing, invalid, expired, or revoked keys return 401. A valid key without the required scope returns 403. Resource IDs are checked within the key's workspace; a foreign ID cannot be used to access another workspace's contact, template, list, or sender.
Rotate by replacement: create a new key, update the application, validate a request, then revoke the old key. Do not revoke the only working key before deploying the replacement.

Webhook authentication differs

Incoming customer webhooks from Convert carry X-Convert-Signature, computed with the endpoint's own signing secret. Your Bearer API key is not that signing secret. See webhook verification.
Next: validate an API request and review errors.
Never embed a customer API key in a signup form or public site. Use the form's supported public integration or your own trusted backend.