Skip to main content

​
Overview

An API key lets your own scripts and tools use the Ascienth console API. You create and manage keys in the console at https://console.advinservers.com, under the “API” group of the “Account” section of the sidebar:
  • “API Keys”: create keys and choose what each one can do.
  • “API IP Groups”: lists of addresses that a key can be restricted to.
For how to send a key with a request, see the API Introduction. Keys and IP groups belong to your own account. You can only create, edit or revoke them while signed in to the console in your browser. An API key can never manage keys or IP groups, so a leaked key cannot give itself more access.
If you do not see the “API” group in the sidebar, the API is not available at the moment.

​
How a Key’s Permissions Work

Each key has two separate lists of permissions:
  • Account permissions cover what a key may do outside every team: invoices, billing, support, your account details and your teams.
  • Team permissions cover what a key may do inside the one team it works in, such as servers, backups, snapshots, the firewall and networking. They use the same names as team roles. See Team Members and Roles.
Every key works in exactly one team, which you choose when you create it. You can only choose a team you own. Resources in any other team are out of the key’s reach. If you delete that team, the key is deleted with it. To use the API with several teams, create a key for each one. The account permissions you can give a key are: Permissions marked Sensitive can spend money, speak to us in your name, or change who else can act on your account. Only give them to keys that need them. When a permission needs another one to work, the other one is ticked for you.

​
Creating an API Key

1

Open the API Keys page

Click “API Keys” in the “API” group of the “Account” section of the sidebar, then click Create API Key.
2

Name the key and choose its account permissions

In the “New API Key” dialog, enter a Name that says what the key is for.Under “Account permissions”, tick what the key may do outside your teams. You can leave this empty if the key only works on servers and other team resources.Under “IP allowlist”, you can pick one or more API IP groups. The key then works only from the addresses in them. Leave it empty to allow any address. See API IP Groups below.Click Next.
3

Choose the team and its permissions

Pick the one team the key works in from Team. Only teams you own are listed.Under “Team permissions”, tick what the key may do in that team. For example, the request in the API Introduction needs View servers.The key must have at least one account or team permission. Click Create.
4

Copy the key

The “API Key Created” dialog shows the key once. Copy it and store it somewhere safe, then click I have saved it.
We store only a hash of each key, so it cannot be shown again after you close the dialog. If you lose it, revoke the key and create a new one.
Keys do not expire. A key works until you revoke it, or until the team it works in is deleted.

​
Managing Your Keys

The “API Keys” page lists every key with these columns:

​
Editing a Key

Click the menu at the end of the key’s row and choose Edit. The dialog has the same two steps as creating a key. Change the name, the permissions, the IP allowlist or the team, then click Save. Changes apply from the key’s next request. The key itself stays the same, so you do not need to update your scripts.

​
Revoking a Key

Click the menu at the end of the key’s row and choose Revoke. Type the key’s name to confirm, then click Revoke.
Requests using a revoked key fail immediately. This cannot be undone.

​
API IP Groups

An API IP group is a named list of IP addresses. When you restrict a key to one or more groups, the key only works from the addresses in them. Requests from anywhere else are refused. We recommend this for keys used from servers with a fixed IP address. One group can guard several keys, so you can keep one list per office or per server and edit it in one place. Changes to a group apply from the next request of every key that uses it.
API IP groups only restrict API keys. They are separate from the “IP Groups” used by firewall rules, and they do not affect signing in to the console in your browser.

​
Creating a Group

1

Open the API IP Groups page

Click “API IP Groups” in the “API” group of the “Account” section of the sidebar, then click Create IP Group.
2

Name the group

Enter a Name, and optionally a Description of where the keys are used from. Click Create.The name can contain letters, numbers, spaces, dots, dashes and underscores, and must be different from your other groups’ names.
3

Add addresses

Click the group’s row, or choose Manage addresses from the menu at the end of it, then click Add Addresses. Enter one IPv4 or IPv6 address or CIDR range per line, such as 203.0.113.10 or 198.51.100.0/24. You can add an optional Note, which is applied to each address you add. Click Add.
4

Restrict a key to the group

On the “API Keys” page, edit the key and pick the group under “IP allowlist”. Save the key.
Ranges written as a start and an end, such as 1.2.3.4-1.2.3.9, are not accepted. Write them as CIDR ranges instead. Addresses already in the group are skipped.
A key restricted to an empty group cannot be used from anywhere. Add addresses to the group before you rely on the key.

​
Editing or Deleting a Group

On a group’s page, use the menu at the end of an address’s row to Edit or Delete it. When you delete an address, every key restricted to the group stops working from that address. On the “API IP Groups” page, the “Used By” column shows how many keys each group guards. Use the menu at the end of a group’s row to Edit its name and description, or to Delete it. A group that still guards a key cannot be deleted. Remove it from those keys, or revoke them, first.

​
Frequently Asked Questions

No. A key can only be limited to a team you own, and only you can create keys on your account. A team member can create keys on their own account, for the teams they own.
The key was created before keys were limited to one team. It works in every team you own. Edit the key and choose a team to limit it to that team.
Yes. Every request made with an API key, including reads, is recorded in your audit log along with the key that made it.