HTTP API

ShellHub’s HTTP API speaks JSON, and it is the same one the console uses. API Reference lists every route; this page is how you get in and what a credential can do once you are.

Authenticating

Two credentials work, and they are for different things.

An API key goes in the X-API-Key header:

$ curl -H "X-API-Key: <your-api-key>" https://cloud.shellhub.io/api/devices

It carries a namespace and a role. It belongs to the namespace rather than to anybody’s session, and any expiry it has is one you set at creation, not a session lifetime the server imposes.

A bearer token is the JWT a person gets from signing in:

$ curl -H "Authorization: Bearer <token>" https://cloud.shellhub.io/api/devices

The role behind it is read again on every request rather than trusted from the token, so a role change takes effect immediately.

Anything unattended should hold an API key. A script driving a bearer token has to handle sign-in and expiry, and if it does that with a person’s credentials it breaks the day that person leaves.

Creating a key

From the console, under Team → API Keys. A key has:

Name keys for what they do: ci-deploy, inventory-sync, not key1. The key’s own routes address it by name. An access policy and an SSH identity refer to it by the id creation returns, so renaming a key breaks neither.

A key is scoped to the one namespace it was created in. It reaches nothing in another namespace, and it is not accepted on the instance administration surface under /admin/api, which takes a credential of its own.

Give a key the least role that does the job, and set an expiry where you can. Most integrations only read, so an observer key is enough, and a key with a deadline stops mattering on its own if somebody forgets it exists. See User Roles.

What a key cannot do

Some routes refuse an API key whatever its role, because they act for a person:

• Creating, listing, updating or deleting API keys, its own included
• Managing provisioning keys
• Generating an invitation link, or accepting an invitation
• Creating, listing or leaving namespaces
• Changing a user’s own profile or password, and anything to do with MFA or the vault
• Approving an SSH login or pairing a device

The refusal is structural, not a permission you can grant.

A key over SSH

An API key’s token never opens an SSH session, and an SSH identity never calls the API. See SSH Access for how the key connects over SSH, enrolling its public key and writing the policy that grants it.

Rotating a key

Create the new key, move consumers to it, then delete the old one. Name them so you can tell them apart mid-rotation, ci-deploy-2026 rather than editing in place. Deleting takes effect immediately, and anything still using the old key starts getting 401.

When a credential is refused

A protected route answers 401 whether the key does not exist, has expired, or was never valid, and does not tell an unauthenticated caller which of those it was. A 401 means “this credential is not usable”, not “this credential does not exist”.

Paginating a response

List routes take page and per_page, and answer the total in the X-Total-Count header:

$ curl -H "X-API-Key: $KEY" \
    "https://cloud.shellhub.io/api/devices?page=1&per_page=100"

The specification

API Reference renders it in the browser. The files are the same thing, to diff or to hand to a generator:

Take the one matching your edition. Editions expose different routes: a Community server has no MFA, firewall rule, or web endpoint routes at all, so a client generated from the wrong file produces methods that answer 404. That is not a permission problem, because the route is not there. See Editions.

Where to go next

• API Reference — Every route, per edition.
• MCP Server — The same API, for AI agents.
• SSH Access — The key’s way in to devices.