Skip to content
IconEngage

Create and manage API keys

Create an API key for each system that calls IconEngage, choose its permissions, copy it once, and revoke or replace it.

An API key lets one of your systems call the IconEngage public API. Create a separate key for each system, so you can revoke one without touching the others.

Note: Owners, Admins and Developers can see and manage API keys. Your plan must include the public API to create one.

The API keys page

Go to Settings › API keys. The page lists your organisation's keys with these columns:

ColumnWhat it shows
NameThe name you gave the key
KeyThe key's public start and its last four characters. The full key is never shown again after you create it.
PermissionsHow many permissions the key carries. Hover to see them.
Last usedWhen the key last made a request, or Never
CreatedWhen the key was created
StatusActive or Revoked

Revoked keys are hidden. Turn on Show revoked keys to see them.

The page also shows the address your keys work with, as Public API: ….

Create a key

  1. Go to Settings › API keys.
  2. Click New API key.
  3. In Name, name the key after the system that will use it, for example "Order sync". Names are up to 120 characters, and two active keys cannot share a name.
  4. Under Permissions, tick what the key needs. Type in Filter permissions to find one. Give the key only what it needs: for example messages.send and messages.read to send messages and check their status.
  5. Click Create key.
  6. If you have not confirmed your identity in the last few minutes, IconEngage asks for your two-factor code or your password. Enter it to continue.
  7. Copy the key from Copy your API key now and store it somewhere safe, such as your server's secret store or a password manager.
  8. Click I have copied it.

Note: This is the only time the key is shown. IconEngage stores only a one-way hash of it, so nobody (including support) can recover it. If you lose it, create a new key.

Which permissions a key can have

The list only shows permissions you hold yourself, and a key can carry up to 64. Each API endpoint needs one permission; the API overview lists which.

A key never does more than the person who created it:

  • It acts with its creator's authority, checked on every request. If the creator's role later loses a permission, the key loses it too, and requests needing it are refused.
  • If the creator leaves the organisation or is suspended, all their keys stop working.

Tip: For an integration that must outlive any one person, create its keys from an account kept for that purpose. Make sure that account's role has the permissions the integration needs. For example, the Developer role cannot send messages, so a key that sends must be created by someone whose role can.

See Roles and permissions for what each role holds.

Revoke a key

  1. Go to Settings › API keys.
  2. Open the actions menu on the key's row and choose Revoke.
  3. Click Revoke key to confirm.

Anything using the key stops working at once. Revoking cannot be undone.

Replace (rotate) a key

There is no rotate button. To replace a key without downtime:

  1. Create a new key with the same permissions.
  2. Update your system to use the new key.
  3. Check that Last used on the new key updates.
  4. Revoke the old key.

A revoked key's name can be reused, so the new key can carry the old name once the old one is revoked.

Related

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.