API Keys

An API key is what the x-api-key header carries on every API request. Each key holds a separate permission for each API, so one key can add contacts while another only reads suppressions.

Instructions

1. Go to Account > API Keys. Administrators see this tab; other roles do not.
2. The grid lists Name, API Key, Permissions, Active and Created On.
3. Add opens a dialog:
   • Name it something you will recognise later, for example "Contact API - Production".
   • Permissions sets every API at once: Read Only, Full Access, or Custom to set them one at a time.
   • Under Custom, each API takes its own level. Contact API and Transactional Email API offer Full Access or None. Suppression API also offers Read Only.
4. Create saves the key.
5. Use Edit to rename a key or change its permissions, and the Active switch to turn one off without deleting it. A key that is off is rejected.

Which permission an API needs

What the errors mean

• 401 — the x-api-key header is missing, or the key is not recognised.
• 403 — the key is valid but does not carry the permission that API needs. Edit the key and set it.

Treat a key like a password. Anyone holding it can act on your account through the API.

Related pages

• API Keys Walkthrough — creating a key with screenshots
• Contact API — adding and updating contacts
• Transactional Email API — sending a single email
• Suppression API — reading and writing suppressions
• User Roles — which roles can see this tab