Keys, users and who sees what

Keys

An API key authenticates a system, not a person. You create one under API keys and it is shown once, at the moment it is created.

cconnect_8f3c2a91d7e4b605f2c8a1d9e7b43c50a6f28d91

If you lose it there is no way to get it back: we keep a hash and not the key. The way forward is to create another and revoke the old one.

Give it a name that still makes sense in six months. "Production", "Billing", "Shop integration". After a year with four keys called "test", nobody knows which one can be revoked.

The scope

When creating one you can limit the key to a stream. A key limited to transactional cannot send through a marketing domain, and the request comes back with 403.

It is worth doing when the systems are different, and they usually are: the campaign tool and the application that issues receipts are rarely the same thing.

A key can do everything else the API allows: read messages and events, manage domains, suppressions and webhooks. There are no finer permissions than that, and we did not invent any: a control that exists but checks nothing is worse than no control.

Revoking

The Revoke button cuts access immediately. Any system using that key stops being able to send at that instant, and there is no way to put it back.

The order that avoids an outage:

1. Create the new key.
2. Put it in the system and confirm a send works.
3. Revoke the old one.

To find out whether a key is still in use, look at Last used in the list. A key unused for months is a key to revoke.

Where a key shows up

After it is created, the panel shows only the prefix, the first few characters. That is enough to tell two keys apart and to recognise one in somebody's logs, and not enough to use it.

The full key never appears in the records we keep. It should not appear in yours either: a system that writes the Authorization header to a log is storing the key in the clear somewhere plenty of people read.

Users

A user is a person who signs into the panel. Accounts are created by us, and there is no open registration: an account exists after a contract, and open registration on a sending platform invites whoever wants to send from somebody else's reputation.

One person can have access to several accounts, which is how an agency manages several clients with one sign in. The switcher at the top of the panel lists exactly the accounts that person may reach.

Every user of an account sees the same thing. There are no roles and no per screen permissions: that would be a control we have no way of enforcing on the API side, and half a control is worse than none.

Leaving an account

If one of our operators enters an account, the panel shows a permanent banner at the top, with the account's name and a way out. It cannot be dismissed: the screens are identical to the client's own, and that is how somebody changes the wrong account's settings without noticing.

What to do if a key is exposed

1. Revoke it. First, before investigating.
2. Create a new one and update the systems.
3. Look at Messages over the period in question, for sends you do not recognise.
4. If something was sent that should not have been, tell us: IP reputation is shared, and we can help limit the damage.