Authentication

GuidesUpdated June 14, 2026

Authentication

All API requests must include your API key.

How to send the API key

Use one of these:

  1. Bearer token (recommended)
    Header:
    Authorization: Bearer <your_api_key>

  2. X-API-Key header
    Header:
    X-API-Key: <your_api_key>

Example:

curl -X GET "https://app.machfive.io/api/v1/campaigns" \
  -H "Authorization: Bearer mf_live_a1b2c3d4e5f60718293a4b5c6d7e8f90"

Invalid or missing key

  • Missing key: Response 401 with error: "UNAUTHORIZED", message: "Missing API key. Use Authorization: Bearer <key> or X-API-Key."
  • Invalid key: Response 401 with error: "UNAUTHORIZED", message: "Invalid API key."

Scopes

API keys can be scoped to limit what they can do. A request that needs a scope the key doesn't hold returns 403 FORBIDDEN, with detail listing the required and present scopes.

ScopeGrants
campaigns:readList campaigns, read selections, documents, target audiences, asset options, and build status.
campaigns:writeGenerate sequences and previews; create campaigns, submit target audiences and asset selections, and trigger value-prop generation / builds.
lists:readList lead lists, read list status, export results.
lists:writeRename and delete lists, reprocess lists.
workspace:readRead the workspace profile, documents, and regeneration status.
workspace:writeUpdate workspace details, import documents/URLs, regenerate documents.
signatures:readList email signatures.
signatures:writeCreate, update, and delete email signatures.
agent:readList conversations and read conversation messages.
agent:writeSend agent chat messages.
credits:readRead credit balance and run credit checks.

Keys created without explicit scopes have full access (backward compatibility).

Security

  • Do not commit API keys to source control or expose them in client-side code.
  • Prefer environment variables or a secrets manager.
  • You can create multiple keys (e.g. per environment or integration) and revoke them from the app.

Related guides