Authentication - API Reference - Audienceful

Your API key should never be exposed to a frontend client. Only access the API through a backend service.

Every request to /api/v2/ is authenticated with a workspace API key sent in the X-Api-Key header. There is no session or cookie auth on the v2 API — it is API-key only. A missing or invalid key returns a 401 or 403.

Bash

'X-Api-Key': '<your-api-key>'

Generating an API Key

To generate a key, log in to Audienceful and visit the API keys page within Settings. Next, click Generate Key.

On the following screen, fill out the fields as follows:

Key name. Choose a name for the key. This is for your own reference.
(Optional) Select expiration. Choose when the key expires. After the interval passes, the key can no longer authenticate to the API and it disappears from your account.
(Optional) Scopes. Restrict what the key can do (see below).

When you click Generate Key, your key is generated and presented to you on your API keys page. This is the only time you'll be able to see your token, so ensure you save it.

It's imperative that you do not share this key with any unauthorized users. Should a bad actor get access to your key, you can simply delete it from the settings page above and it will no longer work.

Scopes

Keys may carry scopes that restrict which endpoints they can call. A key created without scopes has full workspace access — this is the default and keeps every existing key working. When scopes are set, each endpoint requires a specific scope.

Scope	Grants
`people:read`	Read contacts
`people:write`	Create / update / delete contacts
`fields:read`	Read custom fields
`fields:write`	Create / update / delete custom fields
`audiences:read`	Read audiences + member counts
`events:read`	List custom automation events
`events:write`	Trigger automation events
`emails:send`	Send transactional emails
`reports:read`	Read send reports + request logs
`webhooks:read`	Read webhook endpoints
`webhooks:write`	Manage webhook endpoints

write does not imply read — grant both when your integration needs to both read and mutate a resource.

A request whose key lacks the required scope returns a 403 with a permission_error naming the missing scope:

JSON

{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "This API key is missing the required scope: people:write"
  },
  "request_id": "9f2c1a7e5b8d4f31a0c6e2d9b7a4f108"
}

Request & response conventions

Content type. Send and receive JSON (Content-Type: application/json).
Request IDs. Every response carries an X-Request-Id header. You may supply your own via the X-Request-Id request header for correlation; otherwise one is generated. The same value appears as request_id in error responses.

See Errors, Idempotency, and Pagination for the remaining conventions that apply across all endpoints.