openapi: 3.0.3 info: title: ShellHub OpenAPI description: | Full reference for the ShellHub Community 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. components: securitySchemes: jwt: $ref: ./components/schemas/security.yaml#/jwt api-key: $ref: ./components/schemas/security.yaml#/api-key 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. - name: public-keys x-displayName: SSH Public Keys description: Register and manage SSH public keys. - name: access-policies x-displayName: SSH Access Policies description: Manage SSH access policies of a new namespace. - name: ssh-identities x-displayName: SSH Identities description: Manage enrolled SSH key identities of a new namespace. - 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: users x-displayName: Users description: User-scoped namespace security settings. - name: internal description: Requests executed internally by ShellHub server. - name: external description: Requests executed by the ShellHub user. - name: system description: Routes related to running instance. - 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: 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: /info: $ref: paths/api@info.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/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/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/sessions/{uid}/close: $ref: paths/api@sessions@{uid}@close.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/stats: $ref: paths/api@stats.yaml /api/namespaces: get: $ref: paths/api@namespaces.yaml#/get /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/{tenant}/upgrade: $ref: paths/api@namespaces@{tenant}@upgrade.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/devices/tenant-registrations: $ref: paths/api@devices@tenant-registrations.yaml /api/devices/enroll/callback/{token}: $ref: paths/api@devices@enroll@callback@{token}.yaml /api/web-terminal/reauth: $ref: paths/api@web-terminal@reauth.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/register: $ref: paths/api@register.yaml /api/invitations/resolve: $ref: paths/api@invitations@resolve.yaml /api/users/invitations: $ref: paths/api@users@invitations.yaml /api/namespaces/{tenant}/invitations: $ref: paths/api@namespaces@{tenant}@invitations.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/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 /ws/ssh/session: $ref: paths/ws@ssh@session.yaml