# Create and use API tokens

> API tokens let scripts and the rack4 CLI use the API as you. How to create one with the right scope and expiry, store it safely and revoke it.

Source: https://rack4.io/help/api-tokens · Updated: 2026-10-21

An API token lets a script, a CI job or the [rack4 command-line tool](https://rack4.io/help/install-the-rack4-cli) use the Rack4 API as you, without your password. You make one in the panel at [my.rack4.io/account/api-tokens](https://my.rack4.io/account/api-tokens) with a scope, an expiry and optionally the addresses it may be used from, and it is shown once.

The API covers your account, SSH keys, servers, firewalls, snapshots, reverse DNS and invoices. The [API quickstart](https://rack4.io/help/api-quickstart) has examples you can paste.

## Create one

1. Log in and open [Account → API tokens](https://my.rack4.io/account/api-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. Optionally, list the addresses it may be used from in **Only from these addresses**: one address or range per line, like `203.0.113.0/24` or `2001:db8::/48`. From anywhere else the API answers `403 ip_not_allowed`. Leave it empty to allow any address. [Restrict an API token to IP ranges](https://rack4.io/help/restrict-api-token-by-ip) has the details.
6. Type **Your password**. We ask for it so that someone who only has your logged-in browser can't make a token.
7. Choose **create token**.

[Screenshot: The Create a token form with the name github-actions deploy, read and write chosen, an expiry of 90 days and one allowed range, 198.51.100.0/24] A token for a deploy job: read and write, 90 days, and only from the runner's own address range.

You need a [confirmed email address](https://rack4.io/help/verify-your-email) to create a token. An account can hold 10 live tokens at a time; revoke one you no longer use to make room.

[Screenshot: The Create a token form with a name, read only or read and write, an expiry menu, the Only from these addresses box and the password field] Name it after what uses it, and give it the least scope and the shortest life that works.

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.

[Screenshot: The New token box above the list, with the token text outlined and a copy button under it] The new token is shown once, in this box. Copy it straight into a password manager or your CI's secret store.

## Check it worked

Ask the API who you are with the new token. A `200` with your email means the token, its scope and its address limit all let the request through:

```bash
export RACK4_TOKEN="$(cat ~/.rack4-token)"
curl -s -H "Authorization: Bearer $RACK4_TOKEN" https://my.rack4.io/api/v1/me
```

The answer also names the account the token acts on and your role there, which matters if you belong to [a team](https://rack4.io/help/teams).

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, and limit a token to your addresses when it only ever runs from known machines (a CI runner, a server). 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:

```bash
install -m 600 /dev/null ~/.rack4-token
nano ~/.rack4-token
```

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

```bash
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, when it expires, and the addresses it works from. Revoked and expired tokens drop off the list.

[Screenshot: The token list with three tokens: grafana status (read, works from anywhere), ci deploy (read and write, limited to two ranges) and old laptop CLI (read and write, never expires, works from anywhere), each with revoke] A write token that never expires and works from anywhere, like old laptop CLI here, is what the security checkup flags.

**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](https://rack4.io/help/sessions-and-activity) and your SSH keys for anything you didn't do. If you find something, [change your password](https://rack4.io/help/reset-password) and [open a support ticket](https://my.rack4.io/support/new?category=account) straight away.

## Troubleshooting

Every refusal is JSON with a code you can match on. The common ones for tokens:

| Answer | What it means | Fix |
| --- | --- | --- |
| `401 unauthorized`: "Send a valid API token: Authorization: Bearer vps9_…" | The token is missing, mistyped, revoked or expired, or the header isn't `Authorization: Bearer …`. | Check for a stray newline or quote in the secret, then make a new token if it was revoked or expired. |
| `403 insufficient_scope`: "This token does not have the write scope." | A read-only token tried to change something. | Make a read-and-write token for that job. |
| `403 ip_not_allowed`: "This token only works from 198.51.100.0/24; this request came from 203.0.113.7." | The request came from outside the token's addresses. The message names the address we saw. | Add that range, or make a token without a limit for machines whose address changes. |
| `403 forbidden_role` | Your role on a [team account](https://rack4.io/help/teams) can't do this, whatever the token's scope. | Ask an owner or admin to change your role. |

## Next steps

- [API tokens for CI and automation](https://rack4.io/help/api-tokens-for-automation): one token per job, address limits, expiry and rotation.
- [API quickstart](https://rack4.io/help/api-quickstart): first calls in curl, JavaScript, Python, the SDK and the CLI.
- [Rate limits and request ids](https://rack4.io/help/api-rate-limits-and-request-ids).
- [Install the rack4 CLI](https://rack4.io/help/install-the-rack4-cli)
- [Restrict an API token to IP ranges](https://rack4.io/help/restrict-api-token-by-ip)
- [Check your account in the security center](https://rack4.io/help/security-center)