Create and use API tokens

Scripts and the vps9 command-line tool talk to the VPSNine API with a token instead of your password. You make and revoke them in the panel at my.vpsnine.com/account/api-tokens.

The API covers your account, SSH keys, servers, firewalls, snapshots, reverse DNS and invoices. The API quickstart has examples you can paste.

Create one#

1. Log in and open tokens.
2. Give it a Name that says what uses it: laptop CLI, CI deploy, that sort of thing.
3. Pick a Scope. read only can look but not touch. read and write can also add and delete.
4. Pick when it Expires: 30 days, 90 days (the default), a year, or never.
5. Type Your password. We ask for it so that someone who only has your logged-in browser can't make a token.
6. Choose create token.

You need a confirmed email address to create a token. An account can hold 10 live tokens at a time; revoke one you no longer use to make room.

The token appears once, starting with vps9_. Copy it now. We only keep a hash, so we can't show it again; if you lose it, revoke it and make another.

We email you whenever a token is created, so one you didn't make won't go unnoticed.

Limits#

Each token can make 60 requests a minute, and the whole account 120 a minute across all its tokens. Past either, the API answers 429 rate_limited with a Retry-After header.

Passwords and tokens#

Tokens are separate from your password. Changing your password while logged in signs out your other sessions but leaves tokens working, so a routine change doesn't break your scripts. Resetting a forgotten password with an emailed link revokes every token, because a forgotten password might also be a stolen one; make new ones afterwards.

A few habits that help#

Use read only for anything that just reports, like a monitoring script. Make one token per machine or script, so a leak means revoking one token rather than breaking everything. And give tokens an expiry where you can. A token that dies on its own can't sit forgotten in an old backup for years.

Keep it out of sight#

A token can do whatever its scope allows, as you. So keep it out of shell history, code and Git.

A file only you can read works well. Create it, then paste the token in with the editor:

install -m 600 /dev/null ~/.vps9-token
nano ~/.vps9-token

If the file sits inside a project folder, make sure Git can never pick it up:

echo '.vps9-token' >> .gitignore

In CI, use the system's secret store rather than a value in a committed file.

Revoking#

The token list shows each token's name, its first few characters (vps9_abcd…), scopes, when it was created, when it was last used, and when it expires. Revoked and expired tokens drop off the list.

revoke stops a token immediately. Do it when a laptop or server holding it is lost, sold or rebuilt; when it might have been committed somewhere, private repos included; when someone who knew it moves on; or when last used shows activity you can't account for.

If a token has leaked, revoke it first and make the replacement second. Then look over the activity log and your SSH keys for anything you didn't do. If you find something, change your password and open a support ticket straight away.