Keeping your API keys safe
An API key works like a password. Treat it like one
Last reviewed
Storing a key
- Keep it on a server. Never put a key in a web page, a mobile app or any other code that runs on someone else’s device: anyone can read it there.
- Keep it out of source control. Load it from an environment variable or a secrets manager, not from a file you commit.
- Keep it out of logs. Log the
X-Request-IDof a call, never itsAuthorizationheader. - Use a test key while you build. Test keys only reach demo data, so a mistake cannot touch real records.
Giving a key only what it needs
Each key carries scopes, and it can only do what its scopes allow. Give each tool its own key with the fewest scopes it needs: a reporting tool that only reads should never hold a write scope.
Do not assume one scope includes another. On the Portfolio API, for example, a key with a write scope cannot read unless it also holds the matching read scope. Each API guide lists its scopes.
Rotating and revoking keys
- Rotate on a schedule and whenever someone who knew the key leaves.
- Revoke a key you no longer use. A revoked key can never be used again.
- Check when each key was last used. A key in use that you do not recognise is a sign it has leaked.
The steps for each API:
If a key leaks
- Revoke it straight away in your account, then issue a new key to the tools that need one.
- Tell us through the contact form. Say which key it was by its name or the first few characters, never the whole key, and when you think it leaked.
- Check its recent use for calls you did not make, and quote their
X-Request-IDvalues in your message.
What we record when your key is used
- Metadata only. For every call we record when it happened, the method, the path (with record ids, never a query string), the response status, the IP address it came from and the name of the calling software (its user agent, up to 256 characters). We never store request or response bodies, and never your key.
- Changes are named, values are not. When a key creates, changes or deletes something, we record which key did it, what it changed and the names of the fields it touched. Values that could be personal or secret, such as document content, are recorded as hidden.
- Kept for 90 days. Older request records are deleted automatically.
Where to see it:
- Portfolio and professional keys: open Request log on the key. See managing keys.
- Corporate keys: an organisation owner opens Request log on the key in organisation settings.
- To keep a copy, organisation owners can export the audit log as a CSV file.
Checking webhook signatures
Every webhook we send is signed with a secret only you and we know. Check the signature on every delivery before you act on it, and reject any delivery whose signature does not match. Keep the webhook secret on your server, as you would an API key, and replace it if it leaks.
How to check the signature for each API:
Can’t find what you’re looking for?
Our support team is here to help. Contact us and we’ll get back to you as soon as possible.
Contact us
