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.

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 API key operations in the reference accept a signed-in console session and answer 401 to a request that carries a key, so one key cannot create, list or change another.

Operations a key cannot call

The API key group is one of nine that work with a console session and not with a key. The others are the organization's own settings (except Get entitlements, which takes a key), members, invitations, roles, notifications, your user profile, support tickets and the currency list. Each of them answers a key with 401, and the cloud console is where those tasks are done.

Key permissions

A new key gets a copy of the permissions the organization's built-in Admin role holds at the moment the key is created, which is why the console labels each key Full Permissions. The copy is never updated. It leaves out the four roles.* permissions, and it lacks any permission added to the platform after the key was made, so an endpoint that checks such a permission answers an older key with 403. A new key picks up the permissions added since.

Keys with fewer permissions than that cannot be created.

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, and entries are set in the console.

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 key fails every request the same way a wrong key does.

Authentication errors

Status	Body	When
`401`	empty, with `WWW-Authenticate: Bearer`	The header is missing, the key is wrong or disabled, the request comes from outside the key's allowed networks, or the operation takes a console session only.
`403`	envelope with `code` `NO_PERMISSION_EXCEPTION`	The key is valid but lacks the permission the endpoint checks.

The 401 does not say which of its causes applied. Check that the operation is not in the session-only list, then the key itself, its status under Manage API Keys in the console and its allowed networks, in that order.