Shellius API

The portal and the shellius terminal client are both clients of one REST API. Anything you can do in the portal, you can do with a request — subject to the same permissions, the same production approval rules, and the same audit log.

AuthenticateBrowse the reference

The basics

Base URL	https://<your-shellius-host>/api — it is your own deployment. There is no central API.
Format	JSON in, JSON out, Content-Type: application/json.
Authentication	Authorization: Bearer <access token>. See Authentication.
Tenancy	Every call is scoped to the organisation of the signed-in user. There is no organisation parameter.
Authorisation	Permission keys, not role names. Each endpoint in the reference lists the key it requires.

Every response uses one envelope:

{ "success": true, "data": { }, "meta": { } }

{ "success": false, "error": { "code": "PERMISSION_DENIED", "message": "…" } }

There are no long-lived API tokens yet

Shellius does not currently issue personal access tokens or service-account keys. A script authenticates the way a person does: it signs in, receives a short-lived access token and a refresh token, and refreshes as needed. Create a dedicated user with a narrow role for automation, and read Authentication before building on this.

Guides

AuthenticationSign in, refresh, handle the second-factor challenge, and the device flow.ErrorsThe error envelope, status codes and the machine-readable codes worth handling.Pagination and rate limitspage, limit and meta — and which endpoints are rate limited.QuickstartSign in, list servers and request access with curl.

Reference

266 endpoints across 33 resources.

Identity

Sign-in and sessionsPassword sign-in, token refresh, the second-factor challenge, invites, password reset and your own login sessions.21 endpointsDevice authorizationThe OAuth 2.0 device flow (RFC 8628) the `shellius` terminal client uses to sign in without handling a password.4 endpointsTwo-factor authenticationEnrol, change and remove your own second factor, and set the organisation policy.10 endpointsSingle sign-onConfigure OIDC providers and run the browser sign-in redirects.24 endpoints

Team

UsersInvite, list, update, deactivate and delete people in the organisation.26 endpointsRolesBuilt-in and custom roles: named sets of permission keys.7 endpointsGroupsGroups of users, used as policy subjects, approvers and customer scope.9 endpoints

Inventory

CustomersThe client or project level that servers belong to.7 endpointsServersSSH and RDP targets: create, update, health, bootstrap links, provisioning and bulk operations.15 endpointsBulk importImport servers and credentials from files.5 endpointsPostureHost posture reports, findings and the service inventory.23 endpointsSearchThe global search behind the command palette.1 endpoint

Access

Access policiesAllow and deny rules that decide who may reach which servers, as whom, and for how long.8 endpointsAccess requestsRequest access, review requests, revoke them, and fetch the credentials an approved request grants.15 endpointsEmail approvalsToken-based approve and deny links sent to approvers by email.2 endpointsCertificatesIssued SSH certificates: list, inspect, revoke, and the verification call hosts make.6 endpointsCertificate authorityThe organisation’s SSH CA key pair.3 endpointsKeystoreStored identities and SSH keys for hosts that cannot use certificates.20 endpointsPersonal vaultA user’s private identities, keys and hosts.7 endpointsQuick ConnectOne-off connections to hosts outside the inventory.8 endpoints

Activity

SessionsLive and historical SSH and RDP sessions, recordings, and termination.5 endpointsTerminalBrowser terminal sessions held by the backend. The terminal stream itself is a WebSocket, not a REST call.8 endpointsAudit logRead, filter and export the append-only audit log.2 endpointsNotificationsIn-app notifications for the signed-in user.3 endpoints

Settings

OrganisationOrganisation profile and access settings, including the production bypass switch.4 endpointsSMTPOutgoing mail over SMTP.4 endpointsEmail providersAPI-based mail providers.1 endpointStorageWhere session recordings are stored.4 endpoints

Host agent

BootstrapMint bootstrap tokens and serve the install script. The script endpoints are called by `curl` on the host, authenticated by the one-time token.6 endpointsHost agentCalls made by managed hosts themselves — heartbeats and login validation — authenticated by the host’s agent token, not a user.2 endpointsTerminal client downloadsInstaller script and binaries for the `shellius` terminal client.3 endpoints

System

HealthLiveness and version. No authentication.2 endpointsMetricsPrometheus metrics, guarded by a static token.1 endpoint

How this reference is built

The reference pages are generated from the backend's route files: the method and path, the permission guard, the rate limiter and the request validation schema are read from the code. Response bodies are not generated, because they cannot be read reliably from the source — each endpoint shows the envelope only. When a field matters to you, call the endpoint against a test deployment.

The API is versioned with the product. It has no separate version prefix, and no compatibility promise across minor releases yet; check the changelog when you upgrade.