# Quickstart

Turn on API access in the client area, create a key, and make your first call. It takes about five minutes.

> **Note.** The API is in private beta and open by invitation only. If you do not see Settings → API, your account has not been invited yet.

## 1. Check you can turn it on

Only the account owner can set up API access. Before it can be turned on:

- You are signed in as the account owner, as yourself (not a team member, and not staff viewing your account).
- The owner's email address is verified.
- The email address on the account is the same as the owner's sign-in email address. Codes go only to that address.
- Two-factor authentication is turned on (Settings → Security).
- The account is active and has been invited.

The API page lists anything that is missing, in plain words.

## 2. Turn on API access

1. Open **Settings → API** in the client area.
2. If you signed in more than 10 minutes ago, sign out and sign in again. This step needs a recent sign-in.
3. Click **Email me a code**. We send a 6-digit code to the owner's address. It works for 10 minutes and only once.
4. Enter the code, accept the API terms, and click **Turn on API access**.

## 3. Create a key

1. Under **Create a key**, give it a label, for example `monitoring`.
2. Pick when it expires: 30, 90 or 365 days.
3. Optionally list the IP addresses it may be used from.
4. Leave the permission at read only for now. Tick more only when your tool needs them. See [Authentication and keys](authentication.md).
5. Enter the emailed code and click **Create key**.

The key is shown once. Copy it into a password manager or your secret store. We keep no copy and never email it. A key looks like `rsw_live_` followed by 38 letters and digits.

Put it in an environment variable:

```bash
export REDSWITCHES_API_KEY='rsw_live_XXXX…'
```

## 4. Make your first call

Check the key works and see what it may do:

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

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

const rs = new RedSwitches({ apiKey: process.env.REDSWITCHES_API_KEY! });
const key = await rs.auth.verify();
console.log(key.label, key.effective_permissions);
```

```python
import os
from redswitches import Client

client = Client(api_key=os.environ["REDSWITCHES_API_KEY"])
key = client.auth.verify()
print(key.label, key.effective_permissions)
```

```go
client := redswitches.NewClient(os.Getenv("REDSWITCHES_API_KEY"))
key, err := client.Auth.Verify(context.Background())
if err != nil {
	log.Fatal(err)
}
fmt.Println(key.Label, key.EffectivePermissions)
```

```json
{
  "id": "key_5",
  "label": "monitoring",
  "hint": "a1B2",
  "env": "live",
  "permissions": ["read"],
  "effective_permissions": ["read"],
  "expires_at": "2027-02-13T09:30:00Z"
}
```

Then list your servers:

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

```ts
const page = await rs.servers.list({ limit: 50 });
for (const s of page.data) console.log(s.id, s.label, s.primary_ip);
```

```python
page = client.servers.list(limit=50)
for s in page.data:
    print(s.id, s.label, s.primary_ip)
```

```go
page, err := client.Servers.List(ctx, &redswitches.ListOptions{Limit: 50})
if err != nil {
	log.Fatal(err)
}
for _, s := range page.Data {
	fmt.Println(s.ID, s.Label, s.PrimaryIP)
}
```

```json
{
  "data": [
    {
      "id": "srv_123",
      "label": "web-1",
      "product": "Instant Dedicated Server E-2388G",
      "location": { "city": "Amsterdam", "country": "NL" },
      "status": "active",
      "primary_ip": "203.0.113.10",
      "billing_cycle": "monthly",
      "next_due_date": "2026-12-15",
      "recurring_amount": "129.00",
      "currency": "USD",
      "created": "2026-11-15"
    }
  ],
  "next_cursor": null
}
```

## If something goes wrong

Every error has the same shape, with a fixed message and a request id:

```json
{
  "error": {
    "code": "invalid_key",
    "message": "Missing or invalid API key. Send it as \"Authorization: Bearer <key>\".",
    "request_id": "01JCX7Q2M8ZK4T6V9B3N5R1W2Y"
  }
}
```

Quote the `request_id` when you contact support. All codes are on [Rate limits and errors](errors.md).

> **Note.** The SDKs, the CLI, the Terraform provider and the MCP server are built but not published yet ([SDKs](sdks.md)). The curl examples work today.

## Next steps

- Keep keys safe: [Authentication and keys](authentication.md).
- Order a server: [Ordering guide](guide-ordering.md).
- Reboot a server: [Power and actions guide](guide-power.md).