
Create a key
1
Start a key
Click “API Keys” under “API”, then
Create API Key.2
Name it and set account permissions
Enter a
Name that says what the key is for. Under “Account permissions”, tick what it may do outside your teams. Leave it empty if the key only works on servers and team resources.Under “IP allowlist”, pick one or more API IP groups to limit where the key works. Leave it empty to allow any address. Click Next.3
Choose the team and its permissions
Pick the team from
Team. Only teams you own are listed. Under “Team permissions”, tick what the key may do there. The request in the API Introduction, for example, needs View servers.The key needs at least one account or team permission. Click Create.4
Copy the key
The “API Key Created” dialog shows the key once. Copy it somewhere safe, then click
I have saved it.We store only a hash, so the key can’t be shown again. If you lose it, revoke it and create a new one.
Permissions
Each key has two permission lists:- Account permissions: what it may do outside any team.
- Team permissions: what it may do inside its one team, such as servers, backups, snapshots, firewall and networking. These use the same names as team roles.
Manage your keys
The “API Keys” list showsName, Team, how many account and team permissions each key has, IP allowlist, Last used and Created. The allowlist shows Any IP, the names of its groups, or Blocked if it’s restricted and has no groups left.
To edit a key, open its row menu, choose Edit, change the name, permissions, allowlist or team, and click Save. Changes apply from the next request, and the key itself stays the same.
To revoke a key, choose Revoke, type its name to confirm, and click Revoke.
Requests with a revoked key fail immediately. You can’t undo this.
API IP groups
An API IP group is a named list of addresses. A key restricted to groups only works from those addresses, and other requests are refused. We recommend this for keys used from servers with a fixed IP. One group can guard several keys, and edits apply from the next request. API IP groups are separate from the “IP Groups” used by firewall rules, and they don’t affect signing in to the console.1
Create the group
Click “API IP Groups” under “API”, then
Create IP Group. Enter a Name and optional Description, and click Create. Names can use letters, numbers, spaces, dots, dashes and underscores, and must be unique.2
Add addresses
Click the group’s row (or choose
Manage addresses), then Add Addresses. Enter one IPv4 or IPv6 address or CIDR range per line, like 203.0.113.10 or 198.51.100.0/24. An optional Note applies to each address. Click Add.3
Restrict a key
Edit the key, pick the group under “IP allowlist”, and save.
1.2.3.4-1.2.3.9 aren’t accepted. Use CIDR. Addresses already in the group are skipped.
On a group’s page, use an address’s row menu to Edit or Delete it. Deleting an address stops every key on that group from working from it. On “API IP Groups”, the “Used By” column shows how many keys each group guards. Use the row menu to Edit or Delete a group. You can’t delete a group that still guards a key, so remove it from those keys or revoke them first.
Common questions
Can a team member create a key for my team?
Can a team member create a key for my team?
No. A key can only be limited to a team you own, and only you can create keys on your account. Members can create keys on their own account for teams they own.
What does 'Account-wide (legacy)' mean in the Team column?
What does 'Account-wide (legacy)' mean in the Team column?
The key predates one-team keys and works in every team you own. Edit it and choose a team to limit it.
Are API requests recorded?
Are API requests recorded?
Yes. Every request, including reads, is recorded in your audit log with the key that made it.