Authentication and keys

Every request carries an API key in the Authorization header. This page covers the key format, permissions, server lists, expiry and every way a key stops working.

Sending the key

Send the key as a Bearer token, and only there:

curl -sS https://api.redswitches.com/v1/account \
  -H "Authorization: Bearer $REDSWITCHES_API_KEY"

import { RedSwitches } from "@redswitches/api";

const rs = new RedSwitches({ apiKey: process.env.REDSWITCHES_API_KEY! });
const account = await rs.account.get();

import os
from redswitches import Client

client = Client(api_key=os.environ["REDSWITCHES_API_KEY"])
account = client.account.get()

client := redswitches.NewClient(os.Getenv("REDSWITCHES_API_KEY"))
account, err := client.Account.Get(context.Background())

{ "id": "acc_100", "status": "active", "currency": "USD" }

• A missing or malformed header, or a key we do not know, is 401 invalid_key.
• Never put a key in a URL. A key anywhere in the address (path or query string) is refused with 400 key_in_url, and every working key found there is revoked at once and the owner is emailed. URLs end up in logs, browser history and referrers.
• Test keys (rsw_test_…) are refused on the live API with 401 test_key.
• Every 401 answer carries WWW-Authenticate: Bearer.

Key format

A key is rsw_live_ followed by 38 letters and digits. The last six characters are a checksum, so a mistyped key is refused without any lookup. We store only a keyed hash of each key: nobody at RedSwitches can show it to you again. The client area shows the last four characters (the hint) so you can tell keys apart.

Creating keys

Keys are made by the account owner on Settings → API in the client area, with a sign-in from the last 10 minutes and a 6-digit code emailed to the owner. See the Quickstart.

The key is shown once, in the page that creates it.

Permissions

A key can do only what its permissions allow. Each one is ticked when the key is made. A permission that is not ticked can never be added later: create a new key instead.

A request that needs a permission the key does not hold is 403 permission_denied.

Server lists

A key with power lists the servers it may act on. You tick them when the key is made. "All servers" means the servers on the account today: a server added later is not covered until the owner changes the list. Changing the list needs a recent sign-in and a new emailed code, like making a key. A power request for a server that is not on the list is 403 permission_denied.

The same server list covers the cancel, reinstall and rescue permissions. Reads are never limited by the server list.

Granted and effective permissions

RedSwitches can switch parts of the API off for everyone (for example ordering or power) while keys keep their permissions. GET /auth/verify shows both lists: permissions is what the key holds, effective_permissions is what works right now.

curl -sS https://api.redswitches.com/v1/auth/verify \
  -H "Authorization: Bearer $REDSWITCHES_API_KEY"

const key = await rs.auth.verify();

key = client.auth.verify()

key, err := client.Auth.Verify(ctx)

{
  "id": "key_5",
  "label": "deploy-bot",
  "hint": "a1B2",
  "env": "live",
  "permissions": ["read", "order", "power"],
  "effective_permissions": ["read", "power"],
  "expires_at": "2027-02-13T09:30:00Z"
}

A request to a part of the API that is switched off answers 503 unavailable.

When a key stops working

A key stops for good in each of these cases. A revoked key never works again, even if API access is turned off and on.

Other refusals that are not about the key itself:

Keeping keys safe

• Give each tool its own key, with only the permissions it needs.
• Use an IP list for keys that can order or power servers.
• Keep keys in a secret store or environment variable, never in code or URLs.
• If a key may have leaked, revoke it at once in the client area.