Authenticate API requests

Send your API key in the Authorization header, understand what the key is allowed to do, and fix 401 and 403 answers.

Every public API request is authenticated with an API key sent as a bearer token. The key also decides which organisation the request works in and what it may do.

Send the key

Put the key in the Authorization header of every request:

Authorization: Bearer iek_…

For example, to list your contacts:

bash

curl https://iconengage.com/api/public/v1/contacts \
  -H "Authorization: Bearer $ICONENGAGE_API_KEY"

Keys start with iek_. Follow these rules:

Use HTTPS, and only this header. Never put a key in a query string or a URL: proxies and logs record those.
Use the public API address. A key works on /api/public/v1 only. The app's own /api/v1 addresses refuse it.
Keep the key on your server. Do not put it in a web page, a mobile app or anything a customer can download.
Don't send an organisation id. The organisation is read from the key. Any organisation id in a request is ignored.

Signing in to the app does not authenticate API calls: a browser session cookie is refused.

To create a key, see Create and manage API keys.

What a key is allowed to do

Each endpoint needs one permission, and the key must carry it. The API overview lists the permission for every endpoint.

What a key can do is worked out fresh on every request. It is the key's own permissions, limited to what its creator holds right now:

If the creator's role loses a permission, the key loses it too. Everything else keeps working.
If the creator leaves the organisation or is suspended, the key stops working entirely.

So "it worked a moment ago" usually means the creator's role changed a moment ago. An Owner or Admin can fix it by restoring the role, or by replacing the key with one created by someone who holds the permission.

When authentication fails

Status	`code`	What it means	What to do
`401`	`unauthenticated`	The key is missing, malformed, unknown, revoked or expired, or its creator is no longer an active member. All of these give the same answer on purpose.	Check the header spelling and that the key is active on the API keys page. Create a new key if needed.
`401`	`unauthenticated` with `details.reason: cookie_not_accepted`	You sent a browser session cookie instead of a key.	Send an API key in the `Authorization` header.
`403`	`permission_denied`	The key, limited by its creator's current role, lacks the permission this endpoint needs. `details.permission` names it.	Create a key with that permission, or ask an Owner or Admin to check the creator's role.
`402`	`plan_feature_unavailable`, `usage_limit_reached` and others	Your organisation's plan or wallet refuses the action. No key can lift it.	See Rate limits and errors.

A 403 looks the same whether or not the thing you asked for exists. A 404 also looks the same for something that doesn't exist and for something that belongs to another organisation.

Example error

json

{
  "code": "permission_denied",
  "message": "…",
  "request_id": "…",
  "details": {
    "permission": "messages.send",
    "evaluated": "per_request"
  }
}

Quote the request_id if you contact support.

Still need help?

Write to us at [email protected] and tell us what you were trying to do. Already a customer? Sign in to IconEngage — the same articles are under Help in the app.