openapi: 3.0.3 info: title: ShellHub Enterprise OpenAPI description: | Full reference for the ShellHub Enterprise 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 Enterprise instance. 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: authentication-settings description: | Defines the routes to configure and retrieve the ShellHub authentication settings. Currently, ShellHub supports both local authentication (email and password) and SAML-based authentication (Single Sign-On). - name: admin description: Routes provide by ShellHub Admin API. - name: license description: Routes related to license resource. - 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. components: securitySchemes: $ref: ./components/schemas/security.yaml 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/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/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 /api/user/saml/auth: $ref: paths/api@user@saml@auth.yaml /api/user/saml/reauth: $ref: paths/api@user@saml@reauth.yaml /api/user/saml/request: $ref: paths/api@user@saml@request.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