openapi/spec/cloud-openapi.yaml
Rama master · réplica de lectura del repositorio original.
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