Getting started

Authentication

Every request carries an organization API key in the X-API-KEY header. Keys are created in the cloud console and can be limited to your own networks.

Send the key in the X-API-KEY 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/services/baremetal \
  --header 'X-API-KEY: <api-key>'

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. Keys start with org_.

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. Six operations check none, and any key of the organization can call them: the bare metal and IP block plan lists and plan lookups, Get entitlements and List SSH keys. Every other operation checks one of these:

Permission	Operations
`organization.baremetal.read`	Every read on a server: its details, status, operations, power state, hardware readings, bandwidth, activity, network capabilities and the images it can install
`organization.baremetal.update`	Renaming a server, its boot mode, and reading or changing its iPXE script
`organization.baremetal.deploy`	Deploying an operating system and running hardware tests, and cancelling either
`organization.baremetal.power`	Power commands and BMC resets
`organization.baremetal.console`	KVM sessions and virtual media
`organization.baremetal.networking`	Creating and deleting a server's logical interfaces, and attaching it to or detaching it from virtual networks
`organization.baremetal.lock`	Locking and unlocking a server
`organization.networking.read`	Reading virtual networks, their prefixes and addresses, VLAN availability and security scan results, and queueing a rescan
`organization.networking.virtual.manage`	Creating, renaming and deleting virtual networks
`organization.networking.addresses.manage`	Reserving, assigning and releasing addresses, and reverse DNS
`organization.billing.read`	Orders, invoices and their PDFs, subscriptions, usage and account credit
`organization.billing.pay`	Paying invoices, buying credit and managing saved cards
`organization.billing.orders.create`	Orders, plus servers and IP blocks created on hourly billing
`organization.billing.subscriptions.manage`	Cancelling subscriptions, servers and IP blocks
`organization.assets.iso.read`	Listing ISO images
`organization.assets.iso.manage`	Uploading and deleting ISO images
`organization.sshkeys.manage`	Adding, changing and deleting SSH keys
`organization.activity.read`	The organization's activity log

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.

Authentication errors

Status	`code`	When
`401`	`UNAUTHENTICATED`	The header is missing; the key is wrong, disabled, expired or deleted; or the request comes from outside the key's allowed networks. The `message` is "Authentication is required or the supplied credentials are invalid."
`401`	`UNAUTHENTICATED`	The operation takes a console session (Operations a key cannot call). The `message` says so.
`403`	`NO_PERMISSION`	The key is valid but lacks the permission the endpoint names.

Both 401 answers carry a WWW-Authenticate header naming the credentials the endpoint accepts: ApiKey header="X-API-KEY" alongside Bearer where a key works, Bearer alone on a console-only operation.

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