Create an API key to connect another system
Create a secret or restricted key in the Developers area, limit it to the permissions and addresses your integration needs, and rotate or revoke it without downtime.
Updated on
An API key lets one of your company's systems, such as accounting software or your own portal, read and change data without a signed-in person. Only the Owner and Administrator roles can open the Developers area.
Before you start#
- Decide what the integration will do, so you pick only the permissions it needs. A restricted key can never hold a permission your own role lacks.
- To try things without touching real data, switch to the sandbox first: test keys can only be created and used there, and live keys only work outside it.
- If the system that will use the key has fixed IP addresses, have them ready.
Step 1: Open the keys#
- In the thin bar along the bottom of the dashboard (shown on wide screens), click Developers.
- Open the API keys tab.
Step 2: Create the key#
- Click New key.
- Under Name, say what the key is for, such as "Accounting system".
- Under Allowed addresses, you can enter IP addresses or CIDR ranges separated by commas. Leave it empty and the key works from any address.
- Under Type, choose Secret: your permissions for a key with the creator's permissions, or Restricted: your choice to pick each permission.
- Under Mode, choose Live or Test.
- For a restricted key, use Filter permissions to find and tick permissions, grouped by area.
- Click Create key.
Step 3: Store the secret#
- Copy the key shown under Key created and put it in the secret store of the system that will use it.
- Close the dialog. The full key is never shown again: the list keeps only its start and last four characters.
What happens next#
- The key appears in the list as Active, with its Type, Mode and number of permissions.
- Open the row for the detail: permissions, Allowed addresses, Last used, Last address and a cURL example to test the key.
- Every request made with the key is recorded under Logs and updates Last used.
- To replace the secret, open the key and click Rotate. Pick the Overlap (Ends immediately, 1 hour, 24 hours or 7 days) during which the old key keeps working, then click Rotate key.
- If a key leaks, click Revoke and confirm. It becomes Revoked and requests that use it are refused straight away.
Common problems#
- You see Choose at least one permission.: a restricted key needs at least one ticked permission.
- You see Test keys are created in the sandbox. or Only test keys can be created in the sandbox.: the mode you chose does not match where you are. Switch workspace or change Mode.
- You see A test key cannot hold permissions that move money.: this installation does not let test keys create payments or other money movements. Untick those write permissions on the test key.
- You see Enter valid IP addresses or CIDR ranges, for example 203.0.113.0/24.: something in Allowed addresses is neither an address nor a range. Correct it or remove it.