Create and manage API keys
One key per system, the narrowest scopes that work, and a rotation plan you have actually written down.
- Last updated
- 7 minute read
- API
An API key lets another system act on behalf of your organisation. Treat each one like a password that belongs to a system rather than a person.
Creating a key
API keys
Connect Signed to your own systems. Keys act on behalf of this organisation.
| Name | Key | Scopes | Last used | Status | |
|---|---|---|---|---|---|
| Website sync | sgn_7Kd2•••••••••••• | signatures:read, users:read | Today | Active | |
| HR system | sgn_3Mf9•••••••••••• | users:write | 14 Sep | Active | |
| Old intranet | sgn_1Qa4•••••••••••• | signatures:read | 2 Jul | Revoked |
A key is shown once when you create it, and only a hash is stored. Scopes narrow what the key can do. A key can never grant more than the person who created it holds.
Step 1 of 3
Create key
Give it a name that says which system uses it. In six months the name is the only thing that will tell you whether it is still needed.
Reduced motion is on, so the tour waits for you. Use the arrows or the list to move through the steps.
Your new API key
Copy it now. You won't be able to see it again.
Key name
Website syncSecret
sgn_7Kd2mQ4tRv8XbN1pLs6YhA3wZc5eJg0UThis is the only time the secret is shown.
Scopes
Scopes
A key holds a set of scopes, and each endpoint needs one. Grant the narrowest set that lets the system do its job.
| Scope | What it allows |
|---|---|
organisation:read | Read organisation details and settings |
organisation:write | Update organisation details and settings |
usage:read | Read usage counts and the daily series |
signatures:read | List and read signature templates |
signatures:write | Create, update, delete and assign templates |
users:read | List and read people |
users:write | Create, update, delete and import people |
departments:read | List and read departments |
departments:write | Create, update and delete departments |
rules:read | List and read assignment rules |
rules:write | Create, update and delete assignment rules |
campaigns:read | List and read banner campaigns |
campaigns:write | Create, update and delete banner campaigns |
signature:read | Look up the signature for an email address |
signature:stamp | Stamp a signature into an outgoing email body |
audit:read | Read the audit log |
keys:read | List and read API keys |
keys:write | Create, update, revoke and rotate API keys |
* | Full access, equivalent to every scope above |
Note: A key can never grant more than the person who created it holds, and it cannot widen its own scopes. A limited key cannot promote itself.
Rate limits, IP allow-lists and expiry
- Rate limits can be set per minute and per day, per key. Exceed either and the API answers 429 with a
Retry-Afterheader. - An IP allow-list restricts where a key can be used from. Wildcards are supported, so
203.0.113.*covers a subnet. - An expiry date makes a key stop working on a known date, which suits temporary integrations and contractors.
Watch out: A key is a bearer credential: anyone holding it can use it from anywhere the allow-list permits. Never put one in client-side JavaScript, a mobile app, or a public repository.
Rotating and revoking
Rotation issues a new secret for the same key. The response is the only place the new secret appears. Old usage records stay attached to the key, so your history does not break.
- Create the replacement key, or rotate the existing one.
- Put the new secret into the system that uses it and deploy.
- Confirm from the key list that the new key has been used.
- Revoke the old key.
- Check the audit log. Entries made by a key name that key, so the changeover is visible.
Tip: Give each system its own key rather than sharing one. When something goes wrong you can revoke exactly one thing, and the usage records tell you which system it was.
Common questions
Can I see a key again after creating it?
No. Only a hash is stored, so the secret is shown once. If you lose it, rotate the key to get a new secret.
What happens to a key when the plan lapses?
Reads keep working. Writes are refused with a 402 and the reason subscription_required, and start working again as soon as the plan is active.
Do keys work in a browser?
Technically yes, and the Try it tester in our API reference does it. In production, call the API from a server. Anything in a browser is visible to whoever opens developer tools.
Related articles
Something here out of date, or a step that did not work? Tell us and we will fix the article. Every page is checked against the running product, so corrections are welcome.