Authentication

Send the key as a Bearer token in the Authorization header on every request. The key belongs to one organization and the API reads the organization from the key itself, so no other header is needed to say which organization a request is for; an X-ORGANIZATION-ID header sent alongside it is ignored.

curl --request GET \
  --url https://api.serverside.com/v1/baremetal \
  --header 'Authorization: Bearer <api-key>'

The API also reads the key from an X-API-KEY header, an alias for the same credential. A request carries one credential only: X-API-KEY together with an Authorization header, or either header sent twice, is refused with 400 (Authentication errors).

Creating a key

The first key comes from the cloud console: on your organization's settings, Manage API Keys has a Create an API Key button. It asks for a name and, optionally, the networks the key will work from. The finished key is displayed once and cannot be shown again, so store it in a secret manager or an environment variable straight away.

A key is 63 characters: org_, then 59 characters of URL-safe base64, which can include - and _. Only a Bearer value that starts with org_ is read as an API key. Any other value is treated as a console session token, so a key pasted without its prefix fails with 401.

Keys are managed in the console only. The endpoints that create, list and change keys take a signed-in console session, so one key cannot create, list or change another.

Operations a key cannot call

The API reference lists every operation a key can call. The rest of the API serves the cloud console: the organization's own settings, members, invitations, roles, API keys, notifications, your user profile, support tickets and the country and currency lists. Each of those operations answers a key with 401 and this body:

{
  "success": false,
  "data": null,
  "code": "UNAUTHENTICATED",
  "message": "This endpoint requires a signed-in user session. Organization API keys are not accepted here.",
  "traceId": "SRV-1A2B-3C4D-5E6F-7A8B"
}

Key permissions

A new key gets every permission the built-in Admin role has on the day the key is created, which is why the console labels each key Full Permissions. The set is never updated afterwards. A permission added to the platform later is missing from keys made before it, and an endpoint that checks it answers such a key with 403; a key created after the change has it.

Each endpoint page in the reference names the permission the operation checks, for example organization.baremetal.deploy on Deploy operating system. Seven operations check none, and any key of the organization can call them: the bare metal and IP block plan lists and plan lookups, List regions, Get entitlements and List SSH keys. Every other operation checks one of these:

Keys with fewer permissions than the Admin role cannot be created, so a new key holds all of them.

Limiting a key to your networks

A key with no allowed networks works from any address. Once a key has at least one, a request from outside all of them is refused as if the key were wrong. An entry is a single address (198.51.100.7) or a network in CIDR form (198.51.100.0/24), IPv4 or IPv6, set in the console; a new key takes up to 100 of them.

The API compares networks against the address Cloudflare reports for the connection. If a restricted key gets a 401 in the request playground, run the same request with cURL from an allowed machine.

Turning a key off

Disabling a key in the console stops it without losing its settings, and deleting it removes it for good. A disabled, deleted or expired key fails every request the same way a wrong key does. Expiry is separate from the on and off switch, so enabling an expired key does not make it work again.

Authentication errors

A key sent both ways answers:

{
  "success": false,
  "data": null,
  "code": "VALIDATION_ERROR",
  "message": "X-API-KEY: Send one credential: the API key in the Authorization header or in X-API-KEY, not both.",
  "traceId": "SRV-1A2B-3C4D-5E6F-7A8B",
  "details": [
    {
      "code": "INVALID_VALUE",
      "message": "Send one credential: the API key in the Authorization header or in X-API-KEY, not both.",
      "field": "X-API-KEY",
      "location": "header"
    }
  ]
}

Both 401 answers carry WWW-Authenticate headers naming the credentials the endpoint accepts: Bearer and ApiKey header="X-API-KEY" where a key works, Bearer alone on a console-only operation, where it stands for the console's session token.

The first 401 does not say which of its causes applied. Check the key itself and that it follows Bearer , then its status under Manage API Keys in the console, then its allowed networks, in that order.