openapi: 3.0.3 info: title: ShellHub Cloud OpenAPI description: | Full reference for the ShellHub Cloud API, covering public, internal, and service-to-service routes. This is the internal source of truth used for client generation and response validation; the customer-facing documentation is a filtered build that exposes only the namespace-scoped, API-key usable surface. contact: name: ShellHub email: contact@shellhub.io license: name: Apache License 2.0 url: https://github.com/shellhub-io/shellhub/blob/master/LICENSE.md version: 0.20.0 servers: - url: / description: ShellHub server as a Cloud instance. components: securitySchemes: $ref: ./components/schemas/security.yaml tags: - name: devices x-displayName: Devices description: List, inspect, accept, reject, rename, and delete devices, and manage their custom fields. - name: containers x-displayName: Containers description: List and manage containers, which are devices running inside containers. - name: sessions x-displayName: Sessions description: List and inspect SSH sessions and their recordings. - name: public-keys x-displayName: SSH Public Keys description: Register and manage SSH public keys. - name: tags x-displayName: Tags description: Create tags and attach them to devices. - name: namespaces x-displayName: Namespace description: Inspect the namespace and manage its settings. - name: stats x-displayName: Statistics description: Aggregate statistics for the namespace, such as device and session counts. - name: firewall x-displayName: Firewall Rules description: Manage firewall rules. - name: tunnels x-displayName: Tunnels description: Create and manage device tunnels. - name: web-endpoints x-displayName: Web Endpoints description: Create and manage web endpoints. - name: users x-displayName: Users description: User-scoped namespace security settings. - name: cloud description: Routes provided by ShellHub Cloud API. - name: vault description: Routes related to the user's encrypted SSH key vault. - name: mfa description: Routes related to MFA - name: instance-api-keys description: | An instance API key authenticates as an instance administrator rather than as a member of a namespace. It carries no namespace and no role, is accepted only under `/admin/api`, and its plaintext is prefixed with `sh_admin_`. A key always expires, and it stops working as soon as the administrator who created it is no longer an instance administrator. Instance API key routes cannot themselves be authenticated with an API key. - name: api-keys description: | An API key is a unique identifier used to access protected endpoints. It has a defined lifespan, is associated with a namespace, and cannot be used to authenticate user routes. Typically, it replaces login-based authentication when automating processes. To utilize an API key, it must be included in the `X-API-KEY` header. API keys are preferred over JWT tokens and will be used even if one is provided. Except for `GET` endpoints, API key-related routes cannot be authenticated with an API key. paths: $ref: community-openapi.yaml#/paths /api/namespaces: $ref: paths/api@namespaces.yaml /api/sessions/{uid}/records/{seat}: $ref: paths/api@sessions@{uid}@records@{seat}.yaml /api/firewall/rules: $ref: paths/api@firewall@rules.yaml /api/firewall/rules/{id}: $ref: paths/api@firewall@rules@{id}.yaml /api/vault: $ref: paths/api@vault.yaml /api/vault/meta: $ref: paths/api@vault@meta.yaml /api/vault/data: $ref: paths/api@vault@data.yaml /api/vault/settings: $ref: paths/api@vault@settings.yaml /api/user/resend_email: $ref: paths/api@user@resend_email.yaml /api/user/{uid}/update_password: $ref: paths/api@user@{uid}@update_password.yaml /api/user/confirm_account: $ref: paths/api@user@confirm_account.yaml /api/user/recover_password: $ref: paths/api@user@recover_password.yaml /api/billing/customer: $ref: paths/api@billing@customer.yaml /api/billing/subscription: $ref: paths/api@billing@subscription.yaml /api/billing/paymentmethod/attach: $ref: paths/api@billing@paymentmethod@attach.yaml /api/billing/paymentmethod/detach: $ref: paths/api@billing@paymentmethod@detach.yaml /api/billing/paymentmethod/default: $ref: paths/api@billing@paymentmethod@default.yaml /api/billing/device-choice: $ref: paths/api@billing@device-choice.yaml /api/billing/devices-most-used: $ref: paths/api@billing@devices-most-used.yaml /api/billing/portal: $ref: paths/api@billing@portal.yaml /api/webhook-billing: $ref: paths/api@webhook-billing.yaml /api/user/mfa/auth: $ref: paths/api@user@mfa@auth.yaml /api/user/mfa/recover: $ref: paths/api@user@mfa@recovery.yaml /api/user/mfa/reset: $ref: paths/api@user@mfa@reset.yaml /api/user/mfa/generate: $ref: paths/api@user@mfa@generate.yaml /api/user/mfa/enable: $ref: paths/api@user@mfa@enable.yaml /api/user/mfa/disable: $ref: paths/api@user@mfa@disable.yaml /api/user/mfa/recovery/disable: $ref: paths/api@user@mfa@recovery@disable.yaml /api/user/mfa/reset/{user-id}: $ref: paths/api@user@mfa@reset@{user-id}.yaml /api/user: $ref: paths/api@user.yaml /api/namespaces/{tenant}/support: $ref: paths/api@namespaces@{tenant}@support.yaml /api/web-endpoints: $ref: paths/api@web-endpoints.yaml /api/web-endpoints/{address}: $ref: paths/api@web-endpoints@{address}.yaml /api/devices/{uid}/tunnels: $ref: paths/api@devices@{uid}@tunnels.yaml /api/devices/{uid}/tunnels/{address}: $ref: paths/api@devices@{uid}@tunnels@{address}.yaml /admin/api/authentication: $ref: paths/admin@api@authentication.yaml /admin/api/authentication/local: $ref: paths/admin@api@authentication@local.yaml /admin/api/authentication/saml: $ref: paths/admin@api@authentication@saml.yaml /admin/api/devices: $ref: paths/admin@api@devices.yaml /admin/api/devices/{uid}: $ref: paths/admin@api@devices@{uid}.yaml /admin/api/firewall/rules: $ref: paths/admin@api@firewall@rules.yaml /admin/api/firewall/rules/{id}: $ref: paths/admin@api@firewall@rules@{id}.yaml /admin/api/sessions: $ref: paths/admin@api@sessions.yaml /admin/api/sessions/{uid}: $ref: paths/admin@api@sessions@{uid}.yaml /admin/api/sshkeys/public-keys: $ref: paths/admin@api@sshkeys@public-keys.yaml /admin/api/namespaces: $ref: paths/admin@api@namespaces.yaml /admin/api/namespaces/{tenant}: $ref: paths/admin@api@namespaces@{tenant}.yaml /admin/api/namespaces-update/{tenantID}: $ref: paths/admin@api@namespaces-update@{tenantID}.yaml /admin/api/login: $ref: paths/admin@api@login.yaml /admin/api/users: $ref: paths/admin@api@users.yaml /admin/api/users/{id}: $ref: paths/admin@api@users@{id}.yaml /admin/api/users/{id}/password/reset: $ref: paths/admin@api@users@{id}@password@reset.yaml /admin/api/users/{id}/approve: $ref: paths/admin@api@users@{id}@approve.yaml /admin/api/stats: $ref: paths/admin@api@stats.yaml /admin/api/telemetry: $ref: paths/admin@api@telemetry.yaml /admin/api/license: $ref: paths/admin@api@license.yaml /admin/api/instance-api-keys: $ref: paths/admin@api@instance-api-keys.yaml /admin/api/instance-api-keys/{name}: $ref: paths/admin@api@instance-api-keys@{name}.yaml /admin/api/auth/token/{id}: $ref: paths/admin@api@auth@token@{id}.yaml /admin/api/export/namespaces: $ref: paths/admin@api@export@namespaces.yaml /admin/api/export/users: $ref: paths/admin@api@export@users.yaml