API keys and permissions - InstantCampaign

An API key lets an external application, such as your website backend, a script or an integration platform, call the InstantCampaign API on behalf of your workspace. Each key belongs to one workspace and can be limited to specific permissions (scopes).

Managing API keys needs the API keys permission. Owners and Administrators have it, and a custom role can grant it. Members without it do not see API Keys in the settings menu.

Create a key

Open API Keys

Go to Settings → Developers → API Keys and click Create New Key.

Name the key

Enter a Key Name that says where the key will be used, for example “Checkout service” or “Zapier”. The name is only for you; it is how you tell keys apart in the list.

Set an expiry date (optional)

Pick an Expiry Date if the key should stop working on a given day. Leave it empty for a key that never expires.

Choose permissions

Under Permissions, tick the scopes this key needs. They are grouped by what they touch: contacts, lists and segments; events and goals; transactional email and templates; campaigns; journeys; webhooks; AI assistants (MCP). For a key that may call everything, turn on Full access instead. Create Key stays disabled until you either tick at least one scope or turn on Full access.

Create and copy the key

Click Create Key. The Your New API Key dialog shows the full key once. Click Copy Key and store it in your secret manager.

The full key is shown only once. InstantCampaign stores only a hash, so a lost key cannot be recovered. Delete it and create a new one.

The dialog also shows Your first call, a ready-to-run request that lists your contact lists:

curl https://instantcampaign.ai/api/v1/lists \
  -H "Authorization: Bearer ic_your_key_here"

Permissions (scopes)

Give each key only the scopes it needs. A key with scopes can call only the endpoints those scopes cover. Any other call returns 403 with code: "insufficient_scope". Most endpoints also name the missing scope in requiredScope. Transactional send and validate, public events and the MCP server don’t, so check code.

Permission in the app	Scope	Allows
Contacts — read	`contacts:read`	List and search contacts and lists.
Contacts — write	`contacts:write`	Create/update contacts, subscribe and unsubscribe them.
Events — write	`events:write`	Record custom events and goals (including bulk event import and the public events endpoint when called with an `ic_` key).
Transactional — send	`transactional:write`	Send transactional email, and validate a transactional email without sending it.
Transactional — read	`transactional:read`	Read message status and history.
Webhooks — manage	`webhooks:manage`	Register and remove REST hook subscriptions (Zapier, Make), and read the webhook event catalog.
Campaigns — read	`campaigns:read`	List campaigns and when they were sent.
Journeys — trigger	`journeys:trigger`	List API-triggered journeys and start contacts on them.
AI assistant (MCP)	`mcp`	Use the MCP server with this key.

contacts:read also covers custom fields and segments, contacts:write covers creating lists, and transactional:read covers listing templates.

Full access

Full access is a switch of its own, not “nothing ticked”. A full-access key can call every endpoint, including any added to the API later, so the editor shows a warning when you turn it on. Prefer the narrowest scopes that work.

A key for a checkout service that only sends receipts needs just Transactional — send. If that key leaks, it cannot read or export your contacts.

Keys created before scopes existed have no scopes and keep full access. They show a Full access badge in the list.

The key list

Each key shows its Name with its scopes (or Full access), the Prefix (the first characters of the key, so you can match it to your config), when it was Created, when it was Last Used, and when it Expires. An expired key has an Expired badge and is refused by the API.

Revoke a key

Click the delete icon on the key’s row, then Delete Key in the Delete API Key dialog. Any application using the key stops working immediately. To rotate a key without downtime, create the new key first, deploy it, check that the old key’s Last Used date stops changing, then delete the old key.

Change a key’s name or permissions

Open the editor

Click the pencil icon (Edit key) on the key’s row. The Edit API key dialog shows its name and its current scopes.

Change the scopes

Tick or untick scopes, or turn Full access on or off. Turning on Full access for a key that had scopes removes its limits, and the dialog warns you before you save. Turning it off brings back the scopes the key had.

Save

Click Save. The change applies from the key’s next request. The key itself does not change, so nothing needs redeploying.

Every scope change is recorded with who made it and the scopes before and after. Support staff working in your workspace through a support session cannot create, delete or re-scope keys.

Save stays disabled while Full access is off and no scope is ticked: a key with no scopes is stored as full access, so the editor never lets that happen by accident.

Troubleshooting

Response	Cause	Fix
`401 Invalid or missing API key` (`Invalid or expired API key` on the transactional endpoints)	The header is missing, is not `Authorization: Bearer ic_…`, or the key was deleted or has expired	Check the header format and the key’s Expires date
`403` with `insufficient_scope`	The key lacks a scope the endpoint needs (named in `requiredScope`, where the endpoint includes it)	Add that scope to the key (pencil icon → Edit key)
`403` with the workspace-suspended code	The workspace is suspended	Contact support
`429 Rate limit exceeded`	Too many calls from this workspace in one minute	Slow down and retry; limits are per workspace, so all keys share them