Skip to main content
An API key lets your scripts and tools use the Ascienth console API. Manage keys in the console under “Account” > “API”: “API Keys” for the keys, and “API IP Groups” for address lists you can restrict keys to. If you don’t see the “API” group, the API is unavailable right now. To send a key with a request, see the API Introduction. Keys belong to your own account, and you can only manage them while signed in to the console in your browser. A key can never manage keys or IP groups, so a leaked key can’t grant itself more access. API Keys page with account and team tabs

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.
Keys don’t expire. They work until you revoke them or delete their team.

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.
Every key works in exactly one team that you own. Resources in other teams are out of reach, and deleting the team deletes the key. For several teams, create a key for each. Permissions marked Sensitive can spend money, speak to us in your name, or change who can act on your account. When a permission needs another, the other is ticked for you.

Manage your keys

The “API Keys” list shows Name, 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.
Ranges written as 1.2.3.4-1.2.3.9 aren’t accepted. Use CIDR. Addresses already in the group are skipped.
A key restricted to an empty group can’t be used from anywhere. Add addresses first.
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

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.
The key predates one-team keys and works in every team you own. Edit it and choose a team to limit it.
Yes. Every request, including reads, is recorded in your audit log with the key that made it.