Creating and Managing API Keys
API keys let your scripts and tools make changes in the Customer Management Portal without anyone signing in, for example keeping a workspace's IP allowlist up to date when your office IP changes. Keys belong to your agency, carry only the permissions you choose, and are created and revoked from Agency Settings.
Where to find it
Open Agency Settings from the top navigation and select the API Keys tab.
Note: Only Agency Owners can see the API Keys tab and create or revoke keys. Members and Billing Admins do not have access.
Each region has its own portal, and a key only works in the portal where it was created:
Region | Portal | API address |
|---|---|---|
United States |
|
|
Europe |
|
|
How API keys work
A key is a long secret that starts with dfx_. Your script sends it with every request, and the portal checks three things: what the key may do, which workspaces it may touch, and whether it is still valid.
Agency-owned. Keys belong to the agency, not to a person. Every Agency Owner sees all of the agency's keys and can revoke any of them.
Permissions. Each key carries only the permissions you tick when you create it (see the table below). A request outside those permissions is refused.
Workspaces. A key works on the workspaces you select, or on all workspaces in the agency, including ones created later.
Allowed IPs (optional). You can restrict a key so it only works from specific IP addresses or ranges.
Expiry. Every key expires after 30, 90, 180 or 365 days (90 by default).
Shown once. The full key is displayed only when it is created. The portal stores a secure fingerprint of it, never the key itself, so it cannot be shown again.
A key stops working immediately when any of these happens:
It is revoked.
It reaches its expiry date.
The Agency Owner who created it is removed from the agency or is no longer an owner.
Note: Keys are for server-to-server use, such as scripts, scheduled jobs and integrations. They cannot be used from a web browser.
Permissions
Give each key only the permissions its job needs. A broader permission includes the narrower ones listed with it.
Permission | Identifier | What it allows | Includes |
|---|---|---|---|
Workspaces: read |
| List the workspaces the key can access, with their IDs | — |
IP restrictions: read |
| View whether IP restrictions are on and list allowlist entries | — |
IP restrictions: write |
| Add, update and remove allowlist entries | IP restrictions: read |
IP restrictions: admin |
| Turn IP restrictions on or off | IP restrictions: read and write |
Tip: For a script that keeps your office IP on the allowlist, use the Preset: IP updater button. It ticks only IP restrictions: write, so the key cannot turn protection off.
Creating a key
Log in as an Agency Owner.
Open Agency Settings and select the API Keys tab.
Click New key.
Enter a Name that says what the key is for, such as "Office IP updater".
Under Permissions, tick what the key needs, or click Preset: IP updater.
Under Workspaces, tick the workspaces the key may use, or tick All workspaces.
Choose when the key Expires after.
Optionally, enter IP addresses or ranges in Only allow use from these IPs. Leave it blank if the script runs from a changing IP.
Under Confirm it's you, enter your Password. If two-factor authentication is on, also choose a Verification method and enter the Code.
Click Create key.
Click Copy and store the key somewhere safe, such as a password manager or your server's secret store.
Note: The key is shown only once. If you lose it, revoke it and create a new one.
When the key can update IP restrictions on a single workspace, the portal also shows a ready-to-run quick-start command for that workspace.
Note: If your account has neither a password nor two-factor authentication (for example, you only sign in with magic links), set one of them up in Profile before creating keys.
An agency can have up to 25 active keys at a time.
Viewing and revoking keys
The API Keys tab lists every key the agency has created, newest first.
Column | What it shows |
|---|---|
Name | The key's name, its prefix (for example |
Permissions | The permissions the key carries, and any IP addresses it is restricted to |
Workspaces | The workspaces the key can use, or "All workspaces" |
Last used | When the key was last used and from which IP address, or "Never" |
Expires | The expiry date |
Status | Active, Expired or Revoked |
The prefix is the start of the key. Use it to match a key in your scripts to a row in this list.
To revoke a key:
Find the key in the list.
Click Revoke and confirm.
Revoking takes effect immediately, and anything using the key stops working. Revoked and expired keys stay in the list for your records but cannot be reactivated.
Tip: To replace a key that is about to expire, create the new key first, update your script, then revoke the old one.
Notifications and the audit log
Every Agency Owner is emailed when:
Sent when | Includes | |
|---|---|---|
New API Key Created | A key is created | Key name and prefix, permissions, workspaces, expiry date, who created it and from which IP |
IP Restrictions Changed via API | A key adds, changes or removes an allowlist entry, or turns IP restrictions on or off | Workspace, the change made, key name and prefix, and the IP the request came from |
Key activity also appears in Audit Logs:
Action | Actor | Source |
|---|---|---|
Api Key Created, Api Key Revoked | The Agency Owner's email | Your platform name, for example "5000fish Platform" |
Ip Allowlist Entry Added / Updated / Removed, Ip Restriction Enabled / Disabled |
| API |
Api Key Auth Failed | The key prefix, if recognisable | API |
Tip: Look for rows with the API source to see everything your keys have changed.
Tips & best practices
One key per job. Create a separate key for each script or integration, so you can revoke one without breaking the others.
Least privilege. Tick only the permissions and workspaces the job needs. An IP updater needs IP restrictions: write on one workspace, nothing more.
Treat keys like passwords. Never email them, paste them into chat or tickets, or commit them to code repositories. Store them in a password manager or secret store, and give the file holding the key restricted permissions.
Lock fixed-IP scripts to their IP. If a script always runs from the same server, enter that server's IP in Only allow use from these IPs.
Revoke on any doubt. If a key may have been exposed, or the person who managed the script leaves, revoke it and create a new one.
Mind the expiry. Note the expiry date when you create a key and replace the key before it lapses.