openapi: 3.0.3
info:
  title: ShellHub OpenAPI
  description: |
    Full OpenAPI specification for ShellHub, covering every edition and surface.
    This is the internal reference; the customer-facing documentation is a
    filtered build of the per-edition specs.
  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.
components:
  securitySchemes:
    jwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JSON Web Token for authentication.
    api-key:
      type: apiKey
      in: header
      name: X-API-KEY
      description: |
        An API key is an alternative to the standard JWT authentication.
        Authentication with this method is namespace-related and is not tied to any user.
    instance-api-key:
      type: apiKey
      in: header
      name: X-API-KEY
      description: |
        An instance API key authenticates as an instance administrator. It carries no namespace
        and no role, is accepted only under `/admin/api`, and its plaintext is prefixed with
        `sh_admin_`.
tags:
  - name: internal
    description: Requests executed internally by ShellHub server.
  - name: external
    description: Requests executed by the ShellHub user.
  - name: community
    description: Routes provided by ShellHub Community API.
  - name: enterprise
    description: Routes provided by ShellHub Enterprise API.
  - name: cloud
    description: Routes provided by ShellHub Cloud API.
  - name: users
    description: Routes related to user resource.
  - name: devices
    description: Routes related to device resource.
  - name: containers
    description: Routes related to containers resource.
  - name: ssh
    description: Routes related to SSH resource.
  - name: access-policies
    description: Routes related to SSH access policies (new namespaces).
  - name: ssh-identities
    description: Routes related to enrolled SSH key identities (new namespaces).
  - 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.
  - name: provisioning-keys
    description: |
      A provisioning key is a reusable, revocable, namespace-scoped credential that
      auto-accepts a device at install time. It can carry an expiration, a usage
      limit, auto-applied tags, and an ephemeral flag. It is passed to the
      installer as `PROVISIONING_KEY` and is the automation counterpart to the
      interactive browser-based device enrollment.
  - name: system
    description: Routes related to running instance.
  - name: sessions
    description: Routes related to session resource.
  - 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: stats
    description: Routes related to stats resource.
  - name: license
    description: Routes related to license resource.
  - name: firewall
    description: Routes related to firewall rules resource.
  - name: tunnels
    description: Routes related to tunnels resource.
  - name: web-endpoints
    description: Routes related to web-endpoints resource.
  - name: mfa
    description: Routes related to MFA
  - name: vault
    description: Routes related to the user's encrypted SSH key vault.

paths:
  /info:
    $ref: paths/api@info.yaml
  /healthcheck:
    $ref: paths/api@healthcheck.yaml
  /api/login:
    $ref: paths/api@login.yaml
  /api/auth/user:
    $ref: paths/api@auth@user.yaml
  /api/auth/ssh:
    $ref: paths/api@auth@ssh.yaml
  /api/auth/token/{tenant}:
    $ref: paths/api@auth@token@{tenant}.yaml
  /api/devices/{uid}/accept:
    $ref: paths/api@devices@{uid}@accept.yaml
  /api/users:
    $ref: paths/api@users.yaml
  /api/users/{id}/data:
    $ref: paths/api@users@{id}@data.yaml
  /api/users/{id}/password:
    $ref: paths/api@users@{id}@password.yaml
  /api/users/tokens:
    $ref: paths/api@users@tokens.yaml
  /api/users/onboarding-survey:
    $ref: paths/api@users@onboarding-survey.yaml
  /api/users/security/{tenant}:
    $ref: paths/api@users@security@{tenant}.yaml
  /api/namespaces/{tenant}/upgrade:
    $ref: paths/api@namespaces@{tenant}@upgrade.yaml
  /api/devices:
    $ref: paths/api@devices.yaml
  /api/devices/{uid}:
    $ref: paths/api@devices@{uid}.yaml
  /api/devices/resolve:
    $ref: paths/api@devices@resolve.yaml
  /api/devices/locations:
    $ref: paths/api@devices@locations.yaml
  /api/devices/{uid}/{status}:
    $ref: paths/api@devices@{uid}@{status}.yaml
  /api/devices/{uid}/custom_fields/{key}:
    $ref: paths/api@devices@{uid}@custom_fields@{key}.yaml
  /api/devices/{uid}/owner:
    $ref: paths/api@devices@{uid}@owner.yaml
  /api/devices/tenant-registrations:
    $ref: paths/api@devices@tenant-registrations.yaml
  /api/devices/enroll/callback/{token}:
    $ref: paths/api@devices@enroll@callback@{token}.yaml
  /api/devices/auth:
    $ref: paths/api@devices@auth.yaml
  /api/auth/device:
    $ref: paths/api@auth@device.yaml
  /api/devices/auth/challenge:
    $ref: paths/api@devices@auth@challenge.yaml
  /api/devices/auth/code:
    $ref: paths/api@devices@auth@code.yaml
  /api/devices/auth/status:
    $ref: paths/api@devices@auth@status.yaml
  /api/devices/login-code/{code}:
    $ref: paths/api@devices@login-code@{code}.yaml
  /api/devices/pairing:
    $ref: paths/api@devices@pairing.yaml
  /api/devices/pairing/{code}/status:
    $ref: paths/api@devices@pairing@{code}@status.yaml
  /api/devices/pairing/{code}/accept:
    $ref: paths/api@devices@pairing@{code}@accept.yaml
  /api/ssh-approvals/{code}:
    $ref: paths/api@ssh-approvals@{code}.yaml
  /api/ssh-approvals/{code}/confirm:
    $ref: paths/api@ssh-approvals@{code}@confirm.yaml
  /api/ssh-approvals/{code}/reject:
    $ref: paths/api@ssh-approvals@{code}@reject.yaml
  /api/sessions:
    $ref: paths/api@sessions.yaml
  /api/sessions/{uid}:
    $ref: paths/api@sessions@{uid}.yaml
  /api/sshkeys/public-keys:
    $ref: paths/api@sshkeys@public-keys.yaml
  /api/sshkeys/public-keys/{fingerprint}:
    $ref: paths/api@sshkeys@public-keys@{fingerprint}.yaml
  /api/access-policies:
    $ref: paths/api@access-policies.yaml
  /api/access-policies/{id}:
    $ref: paths/api@access-policies@{id}.yaml
  /api/ssh-identities:
    $ref: paths/api@ssh-identities.yaml
  /api/ssh-identities/{id}:
    $ref: paths/api@ssh-identities@{id}.yaml
  /api/web-terminal/reauth:
    $ref: paths/api@web-terminal@reauth.yaml
  /api/stats:
    $ref: paths/api@stats.yaml
  /api/namespaces:
    $ref: paths/api@namespaces.yaml
  /api/namespaces/{tenant}:
    $ref: paths/api@namespaces@{tenant}.yaml
  /api/namespaces/{tenant}/members:
    $ref: paths/api@namespaces@{tenant}@members.yaml
  /api/namespaces/{tenant}/members/{uid}:
    $ref: paths/api@namespaces@{tenant}@members@{uid}.yaml
  /api/namespaces/api-key:
    $ref: paths/api@namespaces@api-key.yaml
  /api/namespaces/api-key/{key}:
    $ref: paths/api@namespaces@api-key@{key}.yaml
  /api/namespaces/api-key/{name}/ssh-identities:
    $ref: paths/api@namespaces@api-key@{name}@ssh-identities.yaml
  /api/namespaces/provisioning-key:
    $ref: paths/api@namespaces@provisioning-key.yaml
  /api/namespaces/provisioning-key/{key}:
    $ref: paths/api@namespaces@provisioning-key@{key}.yaml
  /api/namespaces/provisioning-key/{key}/reveal:
    $ref: paths/api@namespaces@provisioning-key@{key}@reveal.yaml
  /api/namespaces/provisioning-key/{id}/history:
    $ref: paths/api@namespaces@provisioning-key@{id}@history.yaml
  /api/tags:
    $ref: paths/api@tags.yaml
  /api/tags/{name}:
    $ref: paths/api@tags@{name}.yaml
  /api/devices/{uid}/tags/{name}:
    $ref: paths/api@devices@{uid}@tags@{name}.yaml
  /api/containers/{uid}/tags/{name}:
    $ref: paths/api@containers@{uid}@tags@{name}.yaml
  /api/namespaces/{tenant}/tags:
    $ref: paths/api@namespaces@{tenant}@tags.yaml
  /api/namespaces/{tenant}/tags/{name}:
    $ref: paths/api@namespaces@{tenant}@tags@{name}.yaml
  /api/namespaces/{tenant}/devices/{uid}/tags/{name}:
    $ref: paths/api@namespaces@{tenant}@devices@{uid}@tags@{name}.yaml
  /api/namespaces/{tenant}/containers/{uid}/tags/{name}:
    $ref: paths/api@namespaces@{tenant}@containers@{uid}@tags@{name}.yaml
  /api/containers:
    $ref: paths/api@containers.yaml
  /api/containers/{uid}:
    $ref: paths/api@containers@{uid}.yaml
  /api/containers/{uid}/{status}:
    $ref: paths/api@containers@{uid}@{status}.yaml
  /api/setup:
    $ref: paths/api@setup.yaml
  /api/sessions/{uid}/close:
    $ref: paths/api@sessions@{uid}@close.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/register:
    $ref: paths/api@register.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/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
  /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/invitations/resolve:
    $ref: paths/api@invitations@resolve.yaml
  /api/namespaces/{tenant}/invitations/links:
    $ref: paths/api@namespaces@{tenant}@invitations@links.yaml
  /api/namespaces/{tenant}/invitations/accept:
    $ref: paths/api@namespaces@{tenant}@invitations@accept.yaml
  /api/namespaces/{tenant}/invitations/{user-id}:
    $ref: paths/api@namespaces@{tenant}@invitations@{user-id}.yaml
  /api/namespaces/{tenant}/invitations:
    $ref: paths/api@namespaces@{tenant}@invitations.yaml
  /api/users/invitations:
    $ref: paths/api@users@invitations.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
  /ws/ssh/session:
    $ref: paths/ws@ssh@session.yaml