openapi: 3.0.3 info: title: ShellHub Cloud OpenAPI description: | > NOTICE: THE API IS NOT STABLE YET; ERROR AND INCONSISTENCIES MAY OCCUR. ShellHub Cloud OpenAPI specification. It documents all routes provided by ShellHub Cloud. contact: email: contato@ossystems.com.br license: name: Apache License 2.0 url: https://github.com/shellhub-io/shellhub/blob/master/LICENSE.md version: 1.0.0-alpha.4 servers: - url: http://localhost description: ShellHub server as a Cloud instance. components: securitySchemes: jwt: type: http scheme: bearer bearerFormat: JWT description: JSON Web Token for authentication. schemas: info: type: object properties: version: description: ShellHub version. type: string example: latest endpoints: type: object properties: ssh: description: SSH endpoint. type: string example: localhost:2222 api: description: API endpoint. type: string example: localhost userUsername: description: User's username. type: string minLength: 3 maxLength: 30 pattern: ^[a-zA-Z0-9-_.@]$ example: example userPassword: description: User's password. type: string minLength: 5 maxLength: 30 example: example jwt: description: JWT Token type: string pattern: ^[A-Za-z0-9-_]*\.[A-Za-z0-9-_]*\.[A-Za-z0-9-_]*$ example: >- eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJleGFtcGxlIiwibmFtZSI6ImV4YW1wbGUiLCJpYXQiOjE1MTYyMzkwMjJ9.zqCt70KspnNnitZlv89hDbFZ5iGMMRUn0wFEmmlY-to userID: description: User's ID. type: string pattern: ^[0-9a-fA-F]{24}$ example: 507f1f77bcf86cd799439011 userName: description: User's name. type: string minLength: 3 maxLength: 20 example: example userEmail: description: User's E-mail. type: string format: email example: example@example.com namespaceTenantID: description: Namespace's tenant ID type: string pattern: >- ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-4[0-9a-fA-F]{3}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ example: 3dd0d1f8-8246-4519-b11a-a3dd33717f65 namespaceMemberRole: description: Namespace's member role type: string enum: - administrator - operator - observer - owner mfa: description: User MFA status. type: object properties: enable: description: MFA status for the user. type: boolean example: false validate: description: MFA validation status for the token. type: boolean example: false userAuth: type: object properties: token: $ref: '#/components/schemas/jwt' id: $ref: '#/components/schemas/userID' user: $ref: '#/components/schemas/userUsername' name: $ref: '#/components/schemas/userName' email: $ref: '#/components/schemas/userEmail' tenant: $ref: '#/components/schemas/namespaceTenantID' role: $ref: '#/components/schemas/namespaceMemberRole' mfa: $ref: '#/components/schemas/mfa' deviceInfo: description: Device's info type: object properties: id: description: Device's OS name type: string example: example pretty_name: description: Device's OS pretty name type: string example: linux version: description: Device's OS version type: string example: latest arch: description: Device's OS arch type: string example: x86_64 platform: description: Device's OS platform type: string enum: - docker - native example: docker deviceIdentity: description: Device's identity type: object properties: mac: description: Device's MAC type: string pattern: ^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$ example: '00:00:00:00:00:00' deviceUID: description: Device's UID type: string pattern: ^[0-9a-fA-F]{64}$ example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a deviceToken: description: Device's token type: string example: > eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.iUCROHt6JHANdtzT6aOuUgOqVFRalOW20SbzRsn5SkI deviceName: description: | Device's name By default, the name is the device's MAC address when it just added. type: string example: example deviceNamespaceName: description: Device's namespace name type: string example: examplespace publickKeyFingerprint: description: Public key's fingerprint. type: string pattern: ^([0-9a-f]{2}:){15}[0-9a-f]{2}$ example: 48:6e:fc:94:01:01:74:57:eb:57:49:91:15:e4:9c:7a deviceStatus: description: Device's status type: string enum: - accepted - rejected - pending - removed - unused example: accepted namespaceName: description: Namespace's name type: string example: examplespace deviceUpdateAt: description: Device's status update date type: string format: date-format example: '2020-05-01T00:00:00.000Z' tag: description: Tag's name. type: string minLength: 3 maxLength: 255 example: tag deviceTags: description: Device's Tags list type: array items: $ref: '#/components/schemas/tag' minItems: 1 maxItems: 3 example: - tag1 - tag2 - tag3 devicePublicURL: description: Device's public URL status. type: boolean example: false deviceAcceptable: description: > Device's acceptable The value "acceptable" is based on the number of devices removed and already accepted into a namespace. All devices are "acceptable" unless the "namespace.max_devices" is reached. This limit is set based on the sum up of accepted and removed devices into the namespace. When this limit is reached, only removed devices between 720 hours or 30 days are set to "acceptable". type: boolean example: false device: type: object properties: uid: $ref: '#/components/schemas/deviceUID' name: description: | Device's name By default, the name is the device's MAC address when it just added. type: string example: example identity: $ref: '#/components/schemas/deviceIdentity' info: description: Device's info $ref: '#/components/schemas/deviceInfo' public_key: description: Device's public key. type: string example: >- -----BEGIN RSA PUBLIC KEY-----MIIBCgKCAQEA0vH2Bob3mn+uWVaHlOoZD8ai01W6VnRTnXlnHVF7Ny1Vb7pl1Hc4D8bsBhb1vt7aZOYHbCyDR2r5lsrWXCELE8pY8vzfFDA+jNrLbBCJ66E1BcmTqfXCJcLospWD2lIAwU2O7IPxwZujuVkHrF8nYuEFsKeG60QTWNS++RTqydqe2KmFMEdWCQmYPm/ykN871fSR9+PzoRJMYWidY6Szn+X2ardGmS/Ldhl/PEu9h7xjcQXANWz6yV/RVReGVkLcK6TxlfuxgdpbsWAx+cS52P7xWrshNefHqjpdlm3KNbo6vqfTpU8Ld/FFISXXaa1Md5GyAHF+jzuRzQ5z5aKBGwIDAQAB-----END RSA PUBLIC KEY----- tenant_id: $ref: '#/components/schemas/namespaceTenantID' last_seen: description: Device's last seen date type: string format: date-time example: '2020-01-01T00:00:00Z' online: description: Device's availability status type: boolean example: true namespace: description: Device's namespace $ref: '#/components/schemas/namespaceName' status: $ref: '#/components/schemas/deviceStatus' status_update_at: $ref: '#/components/schemas/deviceUpdateAt' created_at: description: Device's creation date type: string format: date-time example: '2020-01-01T00:00:00Z' remote_addr: description: Device's remote address type: string example: 127.0.0.1 position: description: Device's geolocation position type: object properties: latitude: description: Device's latitude position type: number example: -31.7566628 longitude: description: Device's longitude position type: number example: -52.322474 tags: $ref: '#/components/schemas/deviceTags' public_url: $ref: '#/components/schemas/devicePublicURL' acceptable: $ref: '#/components/schemas/deviceAcceptable' sessionUID: description: Session's UID type: string pattern: ^[0-9a-fA-F]{64}$ example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a session: type: object properties: uid: $ref: '#/components/schemas/sessionUID' device_uid: $ref: '#/components/schemas/deviceUID' device: $ref: '#/components/schemas/device' tenant_id: $ref: '#/components/schemas/namespaceTenantID' username: description: Session's username type: string ip_address: description: Session's IP address type: string pattern: ^[0-9]{1,3}(\.[0-9]{1,3}){3}$ example: 127.0.0.1 started_at: description: Session's started date type: string example: '2020-01-01T00:00:00Z' last_seen: description: Session's last seen date type: string example: '2020-01-01T00:00:00Z' active: description: Session's active status type: boolean authenticated: description: Session's authenticated status type: boolean recorded: description: Session's recorded status type: boolean type: description: Session's type type: string enum: - web - term example: web term: description: Session's terminal type: string example: xterm.js position: description: Session's geolocation position type: object properties: latitude: description: Session's latitude position type: number example: -31.7566628 longitude: description: Session's longitude position type: number example: -52.322474 publicKeyData: description: | Public key's data. The `data` field receives the public key enconded as `base64` string. type: string pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$ example: >- c3NoLXJzYSBBQUFBQjNOemFDMXljMkVBQUFBREFRQUJBQUFCQVFDWWdqRkNQUWdPejBEZ0VQQUh3blEyMGYzRUlGYjd2SkNtd1YxR25uRTU2K0htaGgyY295c3o5MnZqMW9GeElxQUlKZUZxU3lQNWwzbDZjbkFUVmxhZ2MxR21OQm5vQ0NZSlpicXdOVUFiM3RMTXdiOXBaSGVWMFczWVl4OERBSVVsL2ZYaVVhQTNpQk5BcTFrczFzYjZjbVN1VmYwTVNTSjdoOXU3c2Y2RnkyVmQ0U1FqSGd3YmNvSUY1Q0kyWkZlMEx6NTNWeGQwVlZRZG5ISGNBeldRVFlTMDIxcmVXeG5QR2RRdytmWXpCRWdRMG5sTmFzQXBRc1pVUXRPZ0t4TlNFcVJ0VnJiRUR4WisrTllQaWFuNUdSZ0huZWNUUzBaVGNjZjM4SDZYTms1Qm5XWGlEN2RCWlJBRnZ1UjBkWEF1cU9mYUM3SVl5MVJnS1lkdEsrUnY= publicKeyFilter: description: > Public key's filter rule. The `filter`` rule defines how if the public key is valid to a device. - When `hostname` object is set, the public key will be used in a device what matches with hostname. - When `tags` object is set, it matches the device what contains at least one of that tags. oneOf: - type: object properties: hostname: description: Public key's regex hostname. type: string example: .* required: - hostname - type: object properties: tags: description: Public key's tags. type: array items: $ref: '#/components/schemas/tag' minItems: 1 maxItems: 3 uniqueItems: true required: - tags publicKeyUsername: description: > Public key's regex username. The `username` field define which user, in the device, may be access through this public key. type: string example: .* publicKeyResponse: type: object properties: data: $ref: '#/components/schemas/publicKeyData' fingerprint: $ref: '#/components/schemas/publickKeyFingerprint' created_at: description: Public key's creation date. type: string format: date-time example: '2020-05-01T00:00:00.000Z' tenant_id: $ref: '#/components/schemas/namespaceTenantID' name: description: Public key's name. type: string example: example filter: $ref: '#/components/schemas/publicKeyFilter' username: $ref: '#/components/schemas/publicKeyUsername' publicKeyRequest: type: object properties: data: $ref: '#/components/schemas/publicKeyData' filter: $ref: '#/components/schemas/publicKeyFilter' name: description: Public key's name. type: string example: example username: $ref: '#/components/schemas/publicKeyUsername' required: - data - filter - name - username namespace: type: object properties: name: $ref: '#/components/schemas/namespaceName' owner: $ref: '#/components/schemas/userID' tenant_id: $ref: '#/components/schemas/namespaceTenantID' members: description: Namespace's members type: array items: type: object properties: id: $ref: '#/components/schemas/userID' role: $ref: '#/components/schemas/namespaceMemberRole' settings: description: Namespace's settings type: object properties: session_record: description: Namespace's session record status type: boolean default: true max_devices: description: Namespace's max device numbers type: integer minimum: 3 default: 3 device_count: description: Namespace's total devices type: integer minimum: 0 created_at: description: Namespace's creation date type: string format: date-time example: '2020-05-01T00:00:00.000Z' billing: description: Namespace's billing type: object example: null announcementUUID: description: Announcement UUID. type: string pattern: >- ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-4[0-9a-fA-F]{3}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ example: 3dd0d1f8-8246-4519-b11a-a3dd33717f65 announcementTitle: description: Announcement title. type: string maxLength: 90 announcementShort: type: object properties: uuid: $ref: '#/components/schemas/announcementUUID' title: $ref: '#/components/schemas/announcementTitle' date: type: string format: date-time example: - title: Lorem ipsum dolor sit amet, consectetur adipiscing elit. date: '2017-07-21T17:32:28Z' - title: Vivamus egestas rhoncus massa, id volutpat sapien porttitor sed. date: '2017-06-21T17:32:28Z' - title: >- Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. date: '2017-05-21T17:32:28Z' announcementContent: description: Announcement description. type: string example: >- # Pendent ignarus ## Inmittitur insula praecipiunt viro odiumque campis securus Lorem markdownum quamvis Sipylus sanguine, *feramus deam* virtus nosse clamor superbia me vivit, lumen. Quid clamore: hi quem. Dea dedit coram, patriam crura dum necis de exanimem. Sub habendus, iubet gentis transformat iter; latet nemus es somnum praecepta saxa. if (firewire(daw, word_southbridge)) { art.api.displayHdtvRom(access * minimize_hover_exif, animated_redundancy); } var drop = real; var pci_mtu_binary = dropPartitionGigabit.open_sound_computer(metal - repositoryUrl, directx_memory + grep_remote_ram, zifFlopsDevice.bar.wimax(ribbonVpiSip, commerce, 65)); if (web) { sectorThird = ipComputerCharacter(5, pppoe_raw_brouter( vpnAnimatedSubnet)); } else { volumeRate += zebibyte_wired * responsiveIo; vram_undo += function_ppc_ole.leaf_graphic(broadbandCleanUdp); pci.compression_source_adsl += frozenServerNvram(tape_io, transistor); } ## Operosa si inque Iacuere ut frontem *primum* nympha nec, ex mihi; nec in! Poma dolori incomitata Nec. Sua senex quod, flavescunt libro nostris cum. 1. Subiere bracchia ergo tumulavit namque inania 2. Ictu bellum 3. Feratis matrumque inritata Ophionides fila agricolis quique ## Quaeritis sitim Velatus quae prodest manet reparabile antraque Pallas viridique [ducentem](http://modo-sic.net/) arcus. Alta per, cum. **Est** vinctum animae anima monte Propoetides praevitiat aliter montibus sua colligit [vasta rabiemque](http://mox.com/pereunt) habet. Edere iste aut, peregrina feramus, iusserat sibilat huius, et. - Corpora a sequor muneris in pietas abdidit - Terribili tantum - Ubi potitur aberat aut animi quaesita manat - Eas duros valerem convivia et videt mirator - Sonitum et ait digna persequitur Trachinia est - Ipse corpora et totis temptaretque neque ## Iterum in tinnulaque frondes culpae spumantis Sub Mavortia illa nudos obstupuere **quantum** secum mitia Apolline tumere, non adhuc audistis ferre. Accepto vocabant movit spe; vere medii adloquitur vano pernocte, everterit harundine simul, sortis causa. Animam [duo causa](http://augustumme.com/puppim) mihi solent in ego quaecumque tarda, et quas: aere quae Avernae Amphitryoniaden. > Ventos fixit culpam vocavit iubasque. Sic venit tam ferinas freto pallescere > vadit: tamen Editus nil te, habet tantum minatur species et enixa. Conplevit > tenens Ladon, fugit studioque ausae Cerberon non maiora, tollit adhuc ait in > quae Atlantiades altae pulcherrime. Anima signa membra cursus, grandior > morientis fidem. Maduere in lacrimis in ultima verbaque pelle. Cervus suas tauro eripitur traho scelerata Hippason et est posse exuit quem per possent valet Alcmena annis et, ut. Utrumque nam nitor sua ultima ferox liquerunt stetimusque **Semeles ianua**. Illi poma implesset sive: inde sub contingere veneratur salientis pectore mirata et Neptunum veniet turis exitium. Quem sensit iam reclusa plus resurgere nescio miratur ibat flamma [tuentes Minervae fortibus](http://intervitae.org/caputex.aspx) canebat et. announcement: description: Announcement. type: object properties: uuid: $ref: '#/components/schemas/announcementUUID' title: $ref: '#/components/schemas/announcementTitle' content: $ref: '#/components/schemas/announcementContent' date: type: string format: date-time recordedSessionResponse: type: array items: type: object properties: uid: description: Session's ID type: string minLength: 64 maxLength: 64 example: 50d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacd0f6545c message: description: Session's Data type: string tenant_id: $ref: '#/components/schemas/namespaceTenantID' time: description: Session's time type: string format: date-time example: '2020-05-01T00:00:00.000Z' width: description: Session's terminal width type: integer minimum: 0 example: 24 height: description: Session's terminal height type: integer minimum: 0 example: 111 required: - uid - message - tenant_id - time - width - height firewallRulesResponse: type: object properties: id: description: Firewall rule's ID. type: string example: 507f1f77bcf86cd799439011 tenant_id: $ref: '#/components/schemas/namespaceTenantID' action: description: Firewall rule's action type: string enum: - allow - deny example: allow active: description: Firewall rule active's status type: boolean example: true filter: description: Firewall rule's filter oneOf: - type: object properties: hostname: description: Firewall rule's hostname type: string example: .* required: - hostname - type: object properties: tags: description: Firewall's rule tags type: array items: type: string minItems: 1 maxItems: 3 example: - tag1 - tag2 - tag3 required: - tags priority: description: Firewall rule's priority type: integer minimum: 0 example: 1 source_ip: description: Firewall rule's source IP regexp type: string example: .* username: description: Firewall rule's username regexp type: string example: .* required: - tenant_id - action - active - filter - priority - source_ip - username firewallRulesRequest: type: object properties: action: description: Firewall rule's action type: string enum: - allow - deny example: allow active: description: Firewall rule active's status type: boolean example: true filter: description: Firewall rule's filter oneOf: - type: object properties: hostname: description: Firewall rule's hostname type: string example: .* required: - hostname - type: object properties: tags: description: Firewall's rule tags type: array items: type: string minItems: 1 maxItems: 3 example: - tag1 - tag2 - tag3 required: - tags priority: description: Firewall rule's priority type: integer minimum: 0 example: 1 source_ip: description: Firewall rule's source IP regexp type: string example: .* username: description: Firewall rule's username regexp type: string example: .* required: - action - active - filter - priority - source_ip - username userMarketing: description: User's email marketing option. type: boolean example: true user: type: object properties: name: $ref: '#/components/schemas/userName' email: $ref: '#/components/schemas/userEmail' username: $ref: '#/components/schemas/userUsername' password: $ref: '#/components/schemas/userPassword' email_marketing: $ref: '#/components/schemas/userMarketing' required: - name - email - username - password enableMFA: description: Enable a MFA type: object properties: token_mfa: description: Token MFA type: string example: '123456' secret: description: Secret MFA type: string example: TWBIH44WRHW44B773HJSG3RNZXH4KWSD codes: description: Secret MFA type: array items: type: string example: - HW2wlxV40B - 2xsmMUHHHb - DTQgVsaVac - KXPBoXvuWD - QQYTPfotBi - XWiKBEPyb4 mfaSecret: description: Secret MFA. type: string example: OYDXN4MO2S2JTASNBG5AD54FVT7A5GVH mfaLink: description: OTP MFA Link. type: string example: >- otpauth://totp/shellhub-enterprise:651101c5b98e9b885e455509?secret=OYDXN4MO2S2JTASNBG5AD57A5GVH&issuer=shellhub-enterprise codes: description: codes type: array items: type: string example: - HW2wlxV40B - 2xsmMUHHHb - DTQgVsaVac - KXPBoXvuWD - QQYTPfotBi - XWiKBEPyb4 recoveryCode: description: Recovery Code MFA type: object properties: code: description: Code for recovery type: string example: VxeTDnFpQkE otpCode: description: OTP Code MFA type: object properties: code: description: OTP code type: string example: VxhDukOuJJ responses: '200': description: Success '400': description: Bad request '401': description: Unauthorized content: application/json: schema: type: object properties: message: description: Error message type: string example: message: missing or malformed jwt '402': description: Payment required '403': description: Forbidden '404': description: Not found '406': description: Not Acceptable '409': description: Conflict '500': description: Internal error content: application/json: schema: type: object properties: message: description: Error message. type: string example: message: Internal Server Error invalidFields: description: Invalid Fields content: application/json: schema: type: array items: type: string example: - username - email conflictFields: description: Conflict Fields content: application/json: schema: type: array items: type: string example: - username - email billingError: description: Error content: application/json: schema: oneOf: - type: object properties: message: description: Error's message. type: string - type: object properties: message: description: Error's message. type: string code: description: Error's code. type: string parameters: namespaceTenantIDPath: name: tenant description: Namespace's tenant ID schema: $ref: '#/components/schemas/namespaceTenantID' required: true in: path deviceUIDPath: name: uid description: Device's UID schema: $ref: '#/components/schemas/deviceUID' required: true in: path filterQuery: name: filter description: > Filter field receives a JSON object enconded as base64 string for limit a search. The JSON enconded must follow these interafaces: ```typescript interface ParamProperty { name: string; operator: "contains" | "eq" | "bool" | "gt" | "lt"; value: string; } interface ParamOperator { name: "and" | "or"; } interface Filter { type: "property" | "operator"; param: ParamOperator | ParamProperty; } interface FilterList { Filters: Array; } ``` ## Examples This is a example to filter and get only the resource what property "confirmed" is "true" ```json [ { "type": "property", "params": { "name": "confirmed", "operator": "bool", "value": "true" } } ] ``` This one, filter resource by the property "id" inside "info" structure when it is equal to "manjaro" and online property is set to "true" ```json [ { "type": "property", "params": { "name": "info.id", "operator": "eq", "value": "manjaro" } }, { "type": "property", "params": { "name": "online", "operator": "bool", "value": "true" } }, { "type": "operator", "params": { "name": "and" } } ] ``` schema: type: string format: byte required: false in: query pageQuery: name: page description: Page number schema: type: integer minimum: 1 default: 1 in: query perPageQuery: name: per_page description: Items per page schema: type: integer minimum: 1 maximum: 100 default: 10 in: query sessionUIDPath: name: uid schema: $ref: '#/components/schemas/sessionUID' required: true in: path publicKeyFingerprintPath: name: fingerprint description: Public key's fingerprint. schema: $ref: '#/components/schemas/publickKeyFingerprint' required: true in: path tagPath: name: tag description: Tag's name. schema: $ref: '#/components/schemas/tag' required: true in: path namespaceMemberIDPath: name: uid description: Member's ID schema: type: string required: true in: path deviceTagPath: name: tag description: Device's tag name schema: $ref: '#/components/schemas/tag' required: true in: path announcementUUID: name: uuid schema: $ref: '#/components/schemas/announcementUUID' required: true in: path tags: - name: cloud description: Routes provided by ShellHub Cloud API. - name: sessions description: Routes related to session resource. - name: users description: Routes related to users resource. - name: rules description: Routes related to firewall rules resource - name: announcements description: Routes related to announcements resource - name: mfa description: Routes related to MFA paths: /api/sessions/{uid}/play: get: operationId: getSessionData summary: Get session recorded data description: Get session recorded data. security: - jwt: [] parameters: - $ref: '#/components/parameters/sessionUIDPath' tags: - cloud - sessions responses: '200': description: Success to get session status. content: application/json: schema: $ref: '#/components/schemas/recordedSessionResponse' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' /api/sessions/{uid}/close: post: operationId: clsoeSession summary: Close session description: Close a session. security: - jwt: [] tags: - cloud - sessions parameters: - $ref: '#/components/parameters/sessionUIDPath' requestBody: content: application/json: schema: type: object properties: device: $ref: '#/components/schemas/deviceUID' required: - device responses: '200': description: Success to close session. '400': $ref: '#/components/responses/400' '500': $ref: '#/components/responses/500' /api/sessions/{uid}/record: post: operationId: recordSession summary: Record session description: Record data about session session. security: - jwt: [] tags: - cloud - sessions parameters: - $ref: '#/components/parameters/sessionUIDPath' requestBody: content: application/json: schema: type: object properties: uid: description: Session's UID. type: string message: description: Session's data. type: string width: description: Session's pty width. type: integer height: description: Session's pty height. type: integer required: - uid - message - width - height responses: '200': description: Success to record session. '400': $ref: '#/components/responses/400' '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: description: Error's message. type: string '500': $ref: '#/components/responses/500' /api/firewall/rules: post: operationId: createFirewallRule summary: Create firewall rule description: Create a firewall rule. tags: - cloud - rules security: - jwt: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/firewallRulesRequest' responses: '200': description: Success to create firewall rule. content: application/json: schema: $ref: '#/components/schemas/firewallRulesResponse' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' get: operationId: getFirewallRules summary: Get firewall rules description: Get a list of firewall rules. tags: - cloud - rules security: - jwt: [] parameters: - $ref: '#/components/parameters/pageQuery' - $ref: '#/components/parameters/perPageQuery' responses: '200': description: Success to get firewall rules. headers: X-Total-Count: description: Firewall rules' total number. schema: type: string minimum: 0 readOnly: true content: application/json: schema: type: array items: $ref: '#/components/schemas/firewallRulesResponse' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' /api/firewall/rules/{id}: parameters: - name: id schema: description: Firewall rule's ID type: integer in: path required: true get: operationId: getFirewallRule summary: Get firewall rule description: Get a firewall rule. tags: - cloud - rules security: - jwt: [] responses: '200': description: Success to get firewall rule. content: application/json: schema: $ref: '#/components/schemas/firewallRulesResponse' '401': $ref: '#/components/responses/401' '500': $ref: '#/components/responses/500' put: operationId: updateFirewallRule summary: Update firewall rule description: Update a firewall rule. tags: - cloud - rules security: - jwt: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/firewallRulesRequest' responses: '200': description: Success to update firewall rule. content: application/json: schema: $ref: '#/components/schemas/firewallRulesResponse' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' delete: operationId: deleteFirewallRule summary: Delete firewall rule description: Delete a firewall rule. tags: - cloud - rules security: - jwt: [] responses: '200': description: Success to delete a firewall rule. '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' /api/firewall/rules/{id}/tags: parameters: - name: id schema: type: string description: Firewall rule's ID required: true in: path post: operationId: ruleAddTag summary: Add a tag to firewall rule description: Add a tag to firewall rule tags: - cloud - rules security: - jwt: [] requestBody: content: application/json: schema: type: object properties: tag: type: string example: tag1 required: - tag responses: '200': description: Success to add tag to firewall rule '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '406': $ref: '#/components/responses/406' '409': $ref: '#/components/responses/409' '500': $ref: '#/components/responses/500' delete: operationId: ruleDeleteTag summary: Remove a tag from firewall rule description: Remove a tag from firewall rule tags: - cloud - rules security: - jwt: [] requestBody: content: application/json: schema: type: object properties: tag: type: string example: tag1 required: - tag responses: '200': description: Success to remove tag from Firewall rule '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' put: operationId: ruleUpdateTags summary: Update tags in firewall rule description: Update tags in firewall rule tags: - cloud - rules security: - jwt: [] requestBody: content: application/json: schema: type: object properties: tags: type: array items: type: string minItems: 1 maxItems: 3 example: - tag1 - tag2 - tag3 required: - tags responses: '200': description: Success to update tags in Firewall rule '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '406': $ref: '#/components/responses/406' '409': $ref: '#/components/responses/409' '500': $ref: '#/components/responses/500' /api/register: post: operationId: registerUser summary: Register user description: Register user tags: - cloud - users security: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/user' responses: '200': description: Success to register user '400': $ref: '#/components/responses/invalidFields' '401': $ref: '#/components/responses/401' '409': $ref: '#/components/responses/conflictFields' '500': $ref: '#/components/responses/500' /api/user/resend_email: post: operationId: resendEmail summary: Resend confirmation description: Resend confirmation to user. tags: - cloud - users security: [] requestBody: content: application/json: schema: type: object properties: username: description: User's username. type: string minLength: 3 maxLength: 20 required: - username example: username: example responses: '200': description: Success to resend confirmation to user. '401': $ref: '#/components/responses/401' '500': $ref: '#/components/responses/500' /api/user/{uid}/update_password: post: operationId: updateRecoverPassword summary: Update user password description: Update user password from a recovery token got from email. tags: - cloud - users security: [] parameters: - name: uid description: User's UID. schema: type: string example: 507f1f77bcf86cd799439011 required: true in: path requestBody: content: application/json: schema: type: object properties: password: $ref: '#/components/schemas/userPassword' token: description: | User's recovery token. It is the token from the email sent to user when the user request password reset. type: string example: password: example token: 3dd0d1f8-8246-4519-b11a-a3dd33717f65 required: - password - token responses: '200': description: Success to update user password. '401': $ref: '#/components/responses/401' '500': $ref: '#/components/responses/500' /api/user/validation_account: get: operationId: getValidateAccount summary: Validate activation link description: Validate the activation link for user. tags: - cloud - users security: [] parameters: - name: email description: User's email. schema: type: string format: email example: example@example.com required: true in: query - name: token description: |- User's validation token. It is a token received from the email used to validate the user. schema: type: string example: 3dd0d1f8-8246-4519-b11a-a3dd33717f65 required: true in: query responses: '200': description: Success to validate user. '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' /api/user/recover_password: post: operationId: recoverPassword summary: Recover password description: Send a recovery email to the user. tags: - cloud - users security: [] requestBody: content: application/json: schema: type: object properties: username: oneOf: - $ref: '#/components/schemas/userUsername' - $ref: '#/components/schemas/userEmail' required: - username responses: '200': description: Success to send email to recover user password. '401': $ref: '#/components/responses/401' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' /api/billing/customer: post: operationId: createCustomer summary: Create customer description: creates a new customer defining, optionaly, the default payment method. security: - jwt: [] tags: - cloud - billing responses: '200': description: Success to create a new customer. '400': description: Bad Request. $ref: '#/components/responses/billingError' '401': description: Unauthorized. $ref: '#/components/responses/billingError' '403': description: Forbidden. $ref: '#/components/responses/billingError' '404': description: Not Found. $ref: '#/components/responses/billingError' '409': description: Conflict. $ref: '#/components/responses/billingError' '424': description: Failed dependency. $ref: '#/components/responses/billingError' '500': $ref: '#/components/responses/500' get: operationId: getCustomer summary: Get Customer description: Get the customer. security: - jwt: [] tags: - cloud - billing responses: '200': description: Success to get a customer. content: application/json: schema: type: object properties: id: description: Customer's ID. type: string example: cus_H9J5n2eZvKYlo2C7X1QX2Qg name: description: Customer's name. type: string example: user email: description: Customer's e-mail. type: string format: email example: user@shellhub.io payment_methods: description: Customer's payment methods. type: array items: type: object properties: id: description: Payment method's ID. type: string example: pm_1H9J5n2eZvKYlo2C7X1QX2Qg number: description: Payment method card's number. type: string example: '4242424242424242' brand: description: Payment method card's brand. type: string example: visa exp_month: description: Payment method card's expiration month. type: integer example: 10 exp_year: description: Payment method card's expiration year. type: integer example: 2030 cvc: description: Payment method card's CVC. type: string example: '123' default: description: Payment method default status. type: boolean example: true '400': $ref: '#/components/responses/billingError' '403': $ref: '#/components/responses/billingError' '404': $ref: '#/components/responses/billingError' '424': $ref: '#/components/responses/billingError' '500': $ref: '#/components/responses/500' /api/billing/subscription: post: operationId: createSubscription summary: Create subscription description: Create a subscription. security: - jwt: [] tags: - cloud - billing responses: '200': description: Success to create a new subscription. '400': $ref: '#/components/responses/billingError' '402': $ref: '#/components/responses/billingError' '403': $ref: '#/components/responses/billingError' '404': $ref: '#/components/responses/billingError' '409': $ref: '#/components/responses/billingError' '424': $ref: '#/components/responses/billingError' '500': $ref: '#/components/responses/500' get: operationId: getSubscription summary: Get subscription description: Get the subscription. security: - jwt: [] tags: - cloud - billing responses: '200': description: Success to get a subscription. content: application/json: schema: type: object properties: id: description: Subscription's ID. type: string example: sub_H9J5n2eZvKYlo2C7X1QX2Qg active: description: Subscription's active. type: boolean example: true status: description: Subscription's status. type: string enum: - inactive - active - trialing - incomplete - incomplete_expired - past_due - canceled - unpaid - paused - to_cancel_at_end_of_period example: active end_at: description: Subscription's current period end. type: integer example: 31536000 invoices: description: Subscription's invoices. type: array items: type: object properties: id: description: Invoice's ID. type: string example: in_H9J5n2eZvKYlo2C7X1QX2Qg status: description: Invoice's status. type: string enum: - draft - open - paid - uncollectible - voided example: open currency: description: Invoice's currency. type: string enum: - usd - brl example: usd amount: description: Invoice's amount in cents. type: integer example: 0 '402': $ref: '#/components/responses/billingError' '403': $ref: '#/components/responses/billingError' '404': $ref: '#/components/responses/billingError' '424': $ref: '#/components/responses/billingError' '500': $ref: '#/components/responses/500' /api/billing/paymentmethod/attach: post: operationId: attachPaymentMethod summary: Attach payment method description: Attachs a payment method to a customer. security: - jwt: [] tags: - cloud - billing requestBody: content: application/json: schema: type: object properties: id: description: Payment method's ID. type: string example: pm_H9J5n2eZvKYlo2C7X1QX2Qg required: - id responses: '200': description: Success to attach the payment method to a customer. '400': $ref: '#/components/responses/billingError' '401': $ref: '#/components/responses/billingError' '403': $ref: '#/components/responses/billingError' '404': $ref: '#/components/responses/billingError' '424': $ref: '#/components/responses/billingError' '500': $ref: '#/components/responses/500' /api/billing/paymentmethod/detach: post: operationId: detachPaymentMethod summary: Detach payment method description: Detachs a payment method from a customer. security: - jwt: [] tags: - cloud - billing requestBody: content: application/json: schema: type: object properties: id: description: Payment method's ID. type: string example: pm_H9J5n2eZvKYlo2C7X1QX2Qg required: - id responses: '200': description: Success to detach the payment method from a customer. '400': $ref: '#/components/responses/billingError' '401': $ref: '#/components/responses/billingError' '403': $ref: '#/components/responses/billingError' '404': $ref: '#/components/responses/billingError' '424': $ref: '#/components/responses/billingError' '500': $ref: '#/components/responses/500' /api/billing/paymentmethod/default: post: operationId: setDefaultPaymentMethod summary: Set default payment method description: Set default payment method to the customer. security: - jwt: [] tags: - cloud - billing requestBody: content: application/json: schema: type: object properties: id: description: Payment method's ID. type: string example: pm_H9J5n2eZvKYlo2C7X1QX2Qg required: - id responses: '200': description: Success to set default payment method. '400': $ref: '#/components/responses/billingError' '401': $ref: '#/components/responses/billingError' '403': $ref: '#/components/responses/billingError' '404': $ref: '#/components/responses/billingError' '424': $ref: '#/components/responses/billingError' '500': $ref: '#/components/responses/500' /api/billing/device-choice: post: operationId: choiceDevices summary: Choice devices description: Choice devices when device's limit is rechead. security: - jwt: [] tags: - cloud - billing requestBody: content: application/json: schema: type: object properties: choices: description: Device's list. type: array items: description: Device's ID. type: string minItems: 0 maxItems: 3 required: - choices responses: '200': description: Success to choice devices. '400': $ref: '#/components/responses/400' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' /api/billing/devices-most-used: get: operationId: getDevicesMostUsed summary: Get devices most used description: Get the most used devices. security: - jwt: [] tags: - cloud - billing responses: '200': description: Success to get the most used devices. headers: X-Total-Count: description: Devices' total number. schema: type: string minimum: 0 readOnly: true content: application/json: schema: type: array items: $ref: '#/components/schemas/device' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' /api/billing/report: post: operationId: report summary: Report description: Report an action. security: - jwt: [] tags: - cloud - billing parameters: - name: action schema: type: string enum: - device_accept - namespace_delete required: true in: query responses: '200': description: Success to report a action. '400': description: Bad Request. content: application/json: schema: description: Error's message. type: string '401': description: Unauthorized. content: application/json: schema: description: Error's message. type: string '402': description: Payment Required. content: application/json: schema: description: Error's message. type: string '403': description: Forbidden. content: application/json: schema: description: Error's message. type: string '404': description: Not found. content: application/json: schema: description: Error's message. type: string '424': description: Failed dependency. content: application/json: schema: description: Error's message. type: string '500': $ref: '#/components/responses/500' /api/billing/evaluate: post: operationId: evaluate summary: Evaluate description: evaluate the namespace capabilities. security: - jwt: [] tags: - cloud - billing responses: '200': description: Success to evaluate the namespace. content: application/json: schema: type: object properties: can_accept: description: Namespaces's acceptance status. type: boolean example: false can_connect: description: Namespace's connection status. type: boolean example: true '400': description: Bad Request. content: application/json: schema: description: Error's message. type: string '401': description: Unauthorized. content: application/json: schema: description: Error's message. type: string '403': description: Forbidden. content: application/json: schema: description: Error's message. type: string '404': description: Not found. content: application/json: schema: description: Error's message. type: string '424': description: Failed dependency. content: application/json: schema: description: Error's message. type: string '500': $ref: '#/components/responses/500' /api/mfa/enable: post: operationId: enableMFA summary: Enable 2fa for the user. description: Enable a MFA. tags: - cloud - mfa security: - jwt: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/enableMFA' responses: '200': description: Success to enable a MFA. content: application/json: schema: type: object properties: token: $ref: '#/components/schemas/jwt' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' /api/mfa/disable: post: operationId: disableMFA summary: Disable MFA status description: Disable a mfa status. tags: - cloud - mfa security: - jwt: [] responses: '200': description: Success to disable a MFA status. '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' /api/mfa/generate: get: operationId: generateMFA summary: Generate MFA connection description: Generate a mfa connection. tags: - cloud - mfa security: - jwt: [] responses: '200': description: Success to generate a mfa connection. content: application/json: schema: type: object properties: secret: $ref: '#/components/schemas/mfaSecret' link: $ref: '#/components/schemas/mfaLink' codes: $ref: '#/components/schemas/codes' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' /api/mfa/recovery: post: operationId: recoveryCodes summary: Checks the code to recover access description: Recovery Code MFA tags: - cloud - mfa security: - jwt: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/recoveryCode' responses: '200': description: Success recover acess with code. content: application/json: schema: type: object properties: token: $ref: '#/components/schemas/jwt' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' /api/mfa/auth: post: operationId: Code summary: Make validation code to MFA connection description: validate MFA to users with MFA Enable. tags: - cloud - mfa security: - jwt: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/otpCode' responses: '200': description: Success to validate a MFA code. content: application/json: schema: type: object properties: token: $ref: '#/components/schemas/jwt' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' /info: get: operationId: getInfo summary: Get info description: >- Get information about ShellHub instance like version, SSH and API addresses. security: [] parameters: - name: agent_version description: Agent's version. schema: type: string required: false in: query responses: '200': description: Success to get ShellHub instance info. content: application/json: schema: $ref: '#/components/schemas/info' '500': $ref: '#/components/responses/500' /api/login: post: operationId: login summary: Login description: >- Authenticate a user, returning the session's JWT token and data about the user. tags: - external - users security: [] requestBody: content: application/json: schema: type: object properties: username: $ref: '#/components/schemas/userUsername' password: $ref: '#/components/schemas/userPassword' required: - username - password responses: '200': description: Success to login. content: application/json: schema: $ref: '#/components/schemas/userAuth' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' /api/auth/user: post: operationId: authUser summary: Auth a user description: >- Authenticate a user, returning the session's JWT token and data about the user. tags: - external - users security: [] requestBody: content: application/json: schema: type: object properties: username: $ref: '#/components/schemas/userUsername' password: $ref: '#/components/schemas/userPassword' required: - username - password responses: '200': description: Success to auth the user. content: application/json: schema: $ref: '#/components/schemas/userAuth' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' get: operationId: getUserInfo summary: Get user info tags: - users security: - jwt: [] responses: '200': description: Success to get the user info. content: application/json: schema: $ref: '#/components/schemas/userAuth' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '500': $ref: '#/components/responses/500' /api/devices/auth: post: operationId: authDevice summary: Auth device description: > Authenticate a ShellHub agent into the ShellHub server. Every 30 seconds, this route is hit by ShellHub agent to inform device availability. tags: - internal - devices security: - jwt: [] parameters: - name: X-Real-IP schema: description: > Device's IP address. `X-Real-IP` header is used to set a geolocation position to device when `geoip` feature is enable. type: string pattern: ^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$ example: 127.0.0.1 in: header requestBody: content: application/json: schema: type: object properties: info: $ref: '#/components/schemas/deviceInfo' sessions: type: array items: type: string hostname: type: string pattern: ([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\-]*[a-zA-Z0-9])\.)* identity: $ref: '#/components/schemas/deviceIdentity' public_key: description: Device's public key. type: string tenant_id: $ref: '#/components/schemas/namespaceTenantID' required: - info - session - hostname - public_key - tenant_id responses: '200': description: Success to auth device. content: application/json: schema: type: object properties: uid: $ref: '#/components/schemas/deviceUID' token: $ref: '#/components/schemas/deviceToken' name: $ref: '#/components/schemas/deviceName' namespace: $ref: '#/components/schemas/deviceNamespaceName' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' /api/auth/device: post: operationId: authDevice summary: Auth device description: > Authenticate a ShellHub agent into the ShellHub server. Every 30 seconds, this route is hit by ShellHub agent to inform device availability. tags: - internal - devices security: - jwt: [] parameters: - name: X-Real-IP schema: description: > Device's IP address. `X-Real-IP` header is used to set a geolocation position to device when `geoip` feature is enable. type: string pattern: ^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$ example: 127.0.0.1 in: header requestBody: content: application/json: schema: type: object properties: info: $ref: '#/components/schemas/deviceInfo' sessions: type: array items: type: string hostname: type: string pattern: ([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\-]*[a-zA-Z0-9])\.)* identity: $ref: '#/components/schemas/deviceIdentity' public_key: description: Device's public key. type: string tenant_id: $ref: '#/components/schemas/namespaceTenantID' required: - info - session - hostname - public_key - tenant_id responses: '200': description: Success to auth device. content: application/json: schema: type: object properties: uid: $ref: '#/components/schemas/deviceUID' token: $ref: '#/components/schemas/deviceToken' name: $ref: '#/components/schemas/deviceName' namespace: $ref: '#/components/schemas/deviceNamespaceName' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' /api/auth/ssh: post: operationId: authSSHPublicKey summary: Auth SSH public key description: Authenticate a SSH public key to ShellHub server. security: - jwt: [] tags: - internal - ssh requestBody: content: application/json: schema: type: object properties: fingerprint: $ref: '#/components/schemas/publickKeyFingerprint' data: description: Public key's data. type: string required: - fingerprint - data responses: '200': description: Success to auth a SSH public key. content: application/json: schema: type: object properties: signature: description: Device's signature. type: string '401': $ref: '#/components/responses/401' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' /api/auth/token/{tenant}: get: operationId: getNamespaceToken summary: Get a new namespace's token description: | This route works like a login's one; returns a JWT token and extra information about namespace. You can use this route to swap between namespaces. tags: - namespaces security: - jwt: [] parameters: - $ref: '#/components/parameters/namespaceTenantIDPath' responses: '200': description: Success to get namespace's token content: application/json: schema: $ref: '#/components/schemas/userAuth' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' /api/token/{tenant}: get: operationId: getToken summary: Get token description: Get a token from its tenant. tags: - users security: - jwt: [] parameters: - name: tenant description: Tenant schema: type: string in: path responses: '200': description: Success get token content: application/json: schema: $ref: '#/components/schemas/userAuth' '401': $ref: '#/components/responses/401' '500': $ref: '#/components/responses/500' /api/devices/{uid}/accept: patch: operationId: acceptDevice summary: Accept device description: Change device status to `accepted`. tags: - devices security: - jwt: [] parameters: - $ref: '#/components/parameters/deviceUIDPath' responses: '200': description: Success to accept the device '401': $ref: '#/components/responses/401' '402': $ref: '#/components/responses/402' '500': $ref: '#/components/responses/500' /api/users/{id}/data: patch: operationId: updateUserData summary: Update user data description: Update user's data. tags: - users security: - jwt: [] parameters: - name: id description: User's ID. schema: type: string required: true in: path requestBody: content: application/json: schema: type: object properties: name: description: User's name. type: string email: description: User's e-mail. type: string format: email username: description: User's username. type: string required: - name - email - username responses: '200': $ref: '#/components/responses/200' '400': $ref: '#/components/responses/invalidFields' '401': $ref: '#/components/responses/401' '404': $ref: '#/components/responses/404' '409': $ref: '#/components/responses/conflictFields' '500': $ref: '#/components/responses/500' /api/users/{id}/password: patch: operationId: updateUserPassword summary: Update user password description: Update only the user password. tags: - users security: - jwt: [] parameters: - name: id description: User ID schema: type: string in: path requestBody: content: application/json: schema: type: object properties: current_password: description: User current password type: string new_password: description: User new password type: string responses: '200': $ref: '#/components/responses/200' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' /api/users/security/{tenant}: put: operationId: setSessionRecord summary: Set session record description: Define if sessions will be recorded. tags: - users - sessions security: - jwt: [] parameters: - $ref: '#/components/parameters/namespaceTenantIDPath' requestBody: content: application/json: schema: type: object properties: session_record: description: Session's record status. type: boolean default: false responses: '200': description: Success to set session record status. '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' /api/users/security: get: operationId: getSessionRecord summary: Get session record description: Get status from if `session record` feature is enable. tags: - users - sessions security: - jwt: [] responses: '200': description: Success get session record status content: application/json: schema: description: Session record status type: boolean '401': $ref: '#/components/responses/401' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' /api/devices: get: operationId: getDevices summary: Get devices description: Get a list of devices. tags: - devices security: - jwt: [] parameters: - $ref: '#/components/parameters/filterQuery' - $ref: '#/components/parameters/pageQuery' - $ref: '#/components/parameters/perPageQuery' - name: status description: Device's status schema: $ref: '#/components/schemas/deviceStatus' default: accepted required: false in: query - name: sort_by description: Device's property to sort of schema: type: string example: name default: last_seen required: false in: query - name: order_by schema: description: Device's list order type: string enum: - asc - desc example: asc default: desc required: false in: query responses: '200': description: Success to get a list of devices. headers: X-Total-Count: description: Devices' total number. schema: type: string minimum: 0 readOnly: true content: application/json: schema: type: array items: $ref: '#/components/schemas/device' '401': $ref: '#/components/responses/401' '500': $ref: '#/components/responses/500' /api/devices/{uid}: parameters: - $ref: '#/components/parameters/deviceUIDPath' get: operationId: getDevice summary: Get device description: Get a device. tags: - devices security: - jwt: [] responses: '200': description: Success get a device. content: application/json: schema: $ref: '#/components/schemas/device' '401': $ref: '#/components/responses/401' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' delete: operationId: deleteDevice summary: Delete device description: Delete a device. tags: - devices security: - jwt: [] responses: '200': description: Success to delete a device. '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' put: operationId: updateDevice summary: Update device description: Update device's data. tags: - devices security: - jwt: [] requestBody: content: application/json: schema: type: object properties: name: $ref: '#/components/schemas/deviceName' public_url: $ref: '#/components/schemas/devicePublicURL' responses: '200': description: Success to update device's data. '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '409': $ref: '#/components/responses/409' '500': $ref: '#/components/responses/500' /api/devices/{uid}/{status}: patch: operationId: updateDeviceStatus summary: Update device status description: Update device's status. tags: - devices security: - jwt: [] parameters: - $ref: '#/components/parameters/deviceUIDPath' - name: status description: Device's status schema: type: string enum: - accept - reject - pending - unused example: accept required: true in: path responses: '200': description: Success to update device status. '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '402': $ref: '#/components/responses/402' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' /internal/devices/{uid}/offline: post: operationId: updateDeviceStatusOffline summary: Update device status to offline description: Update device's status to offiline. tags: - internal - devices security: - jwt: [] parameters: - $ref: '#/components/parameters/deviceUIDPath' responses: '200': description: Success to update device status to offline. '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' /api/sessions: get: operationId: getSessions summary: Get sessions description: Get a list sessions. tags: - sessions security: - jwt: [] parameters: - $ref: '#/components/parameters/pageQuery' - $ref: '#/components/parameters/perPageQuery' responses: '200': description: Success to get list of sessions. headers: X-Total-Count: description: Sessions' total number. schema: type: string minimum: 0 readOnly: true content: application/json: schema: type: array items: $ref: '#/components/schemas/session' '401': $ref: '#/components/responses/401' '500': $ref: '#/components/responses/500' /api/sessions/{uid}: parameters: - $ref: '#/components/parameters/sessionUIDPath' get: operationId: getSession summary: Get session description: Get a session. tags: - sessions security: - jwt: [] responses: '200': description: Success to get a session. content: application/json: schema: $ref: '#/components/schemas/session' '401': $ref: '#/components/responses/401' '500': $ref: '#/components/responses/500' post: operationId: setSessionAuthenticationStatus summary: Set session authentication status description: Set session authentication status. tags: - sessions security: - jwt: [] requestBody: content: application/json: schema: type: object properties: authenticated: description: Session's authentication status. type: boolean responses: '200': $ref: '#/components/responses/200' '401': $ref: '#/components/responses/401' '500': $ref: '#/components/responses/500' /api/sshkeys/public-keys: get: operationId: getPublicKeys summary: Get public keys description: Get a list from all public keys. tags: - ssh security: - jwt: [] parameters: - $ref: '#/components/parameters/filterQuery' - $ref: '#/components/parameters/pageQuery' - $ref: '#/components/parameters/perPageQuery' responses: '200': description: Success to get a list of public keys. headers: X-Total-Count: description: Public keys' total number. schema: type: string minimum: 0 readOnly: true content: application/json: schema: type: array items: $ref: '#/components/schemas/publicKeyResponse' '401': $ref: '#/components/responses/401' '500': $ref: '#/components/responses/500' post: operationId: createPublicKey summary: Create public key description: Create a new public key. tags: - ssh security: - jwt: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/publicKeyRequest' responses: '200': description: Success to create a public key. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/publicKeyData' fingerprint: $ref: '#/components/schemas/publickKeyFingerprint' tenant_id: $ref: '#/components/schemas/namespaceTenantID' name: description: Public key's name. type: string example: example filter: $ref: '#/components/schemas/publicKeyFilter' username: $ref: '#/components/schemas/publicKeyUsername' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '409': $ref: '#/components/responses/409' '422': description: UnprocessableEntity '500': $ref: '#/components/responses/500' /api/sshkeys/public-keys/{fingerprint}: parameters: - $ref: '#/components/parameters/publicKeyFingerprintPath' put: operationId: updatePublicKey summary: Update public key description: Update a public key. tags: - ssh security: - jwt: [] requestBody: content: application/json: schema: type: object properties: name: description: Public key's name. type: string example: example username: description: Public key's username. type: string example: example filter: $ref: '#/components/schemas/publicKeyFilter' required: - name - username - filter responses: '200': description: Success to update a public key. content: application/json: schema: $ref: '#/components/schemas/publicKeyResponse' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' delete: operationId: deletePublicKey summary: Delete public key description: Delete a public key. tags: - ssh security: - jwt: [] responses: '200': description: Success to delete a public key. '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' /api/sshkeys/public-keys/{fingerprint}/tags: parameters: - $ref: '#/components/parameters/publicKeyFingerprintPath' post: operationId: addTagPublicKey summary: Add tag public key description: Add a tag to a public key. tags: - tags - ssh security: - jwt: [] requestBody: content: application/json: schema: type: object properties: tag: description: Public key's tag name. $ref: '#/components/schemas/tag' required: - tag responses: '200': $ref: '#/components/responses/200' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '409': $ref: '#/components/responses/409' '500': $ref: '#/components/responses/500' put: operationId: updateTagsPublicKey summary: Update tags public key description: Update all tags in a public key. tags: - tags - ssh security: - jwt: [] requestBody: content: application/json: schema: type: object properties: tags: description: Public key's new tags. type: array items: $ref: '#/components/schemas/tag' minItems: 1 maxItems: 3 uniqueItems: true example: tags: - tag1 - tag2 - tag3 responses: '200': $ref: '#/components/responses/200' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '409': $ref: '#/components/responses/409' '500': $ref: '#/components/responses/500' /api/sshkeys/public-keys/{fingerprint}/tags/{tag}: parameters: - $ref: '#/components/parameters/publicKeyFingerprintPath' - $ref: '#/components/parameters/tagPath' delete: operationId: removeTagPublicKey summary: Remove tag public key description: Remove a tag from public key. tags: - tags - ssh security: - jwt: [] responses: '200': $ref: '#/components/responses/200' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '409': $ref: '#/components/responses/409' '500': $ref: '#/components/responses/500' /api/stats: get: operationId: getStatusDevices summary: Get stats ShellHub instance description: Get stats ShellHub instance. tags: - devices security: - jwt: [] responses: '200': description: Success get stats from ShellHub instance. content: application/json: schema: type: object properties: registered_devices: description: Number of registered devices type: integer minimum: 0 online_devices: description: Number of online devices type: integer minimum: 0 pending_devices: description: Number of pending devices type: integer minimum: 0 rejected_devices: description: Number of rejected devices type: integer minimum: 0 active_sessions: description: Active sessions type: integer minimum: 0 '401': description: Unauthorized '500': $ref: '#/components/responses/500' /api/namespaces: get: operationId: getNamespaces summary: Get namespaces list description: Returns a list of namespaces. tags: - namespaces security: - jwt: [] parameters: - name: filter description: > Namespaces's filter. Filter field receives a base64 enconded JSON object for limit a search. The JSON object should have a property called `type`, it will filter by a `property` called `name` where the value should `contains` `examplespace`. If you want get only Namespaces name as `examplespace`, the JSON object will looks like this ```json [ { "type":"property", "params":{ "name":"name", "operator":"contains", "value":"examplespace" } } ] ``` So, the output encoded string will result on: `W3sidHlwZSI6InByb3BlcnR5IiwicGFyYW1zIjp7Im5hbWUiOiJuYW1lIiwib3BlcmF0b3IiOiJjb250YWlucyIsInZhbHVlIjoiZXhhbXBsZXNwYWNlIn19XQ==` schema: type: string pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$ example: >- W3sidHlwZSI6InByb3BlcnR5IiwicGFyYW1zIjp7Im5hbWUiOiJuYW1lIiwib3BlcmF0b3IiOiJjb250YWlucyIsInZhbHVlIjoiZXhhbXBsZXNwYWNlIn19XQ== required: false in: query - $ref: '#/components/parameters/pageQuery' - $ref: '#/components/parameters/perPageQuery' responses: '200': description: Success to get a namespace list. headers: X-Total-Count: description: Namespaces' total number. schema: type: string minimum: 0 content: application/json: schema: type: array items: $ref: '#/components/schemas/namespace' '401': $ref: '#/components/responses/401' '500': $ref: '#/components/responses/500' post: operationId: createNamespace summary: Create namespace description: Create a namespace. tags: - namespaces security: - jwt: [] requestBody: content: application/json: schema: type: object properties: name: $ref: '#/components/schemas/namespaceName' required: - name responses: '200': description: Success to create a namespace. content: application/json: schema: $ref: '#/components/schemas/namespace' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '409': $ref: '#/components/responses/409' '500': $ref: '#/components/responses/500' /api/namespaces/{tenant}: parameters: - $ref: '#/components/parameters/namespaceTenantIDPath' get: operationId: getNamespace summary: Get a namespace description: Get a namespace. tags: - namespaces security: - jwt: [] responses: '200': description: Success to get a namespace. content: application/json: schema: $ref: '#/components/schemas/namespace' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' put: operationId: editNamespace summary: Edit namespace description: Edit a namespace. tags: - namespaces security: - jwt: [] requestBody: content: application/json: schema: type: object properties: name: $ref: '#/components/schemas/namespaceName' required: - name responses: '200': description: Success to edit a namespace. content: application/json: schema: $ref: '#/components/schemas/namespace' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '409': $ref: '#/components/responses/409' '500': $ref: '#/components/responses/500' delete: operationId: deleteNamespace summary: Delete namespace description: Delete a namespace. tags: - namespaces security: - jwt: [] responses: '200': description: Success to delete a namespace. '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' /api/namespaces/{tenant}/members: post: operationId: addNamespaceMember summary: Add a member to a namespace description: Add a member to a namespace. tags: - namespaces security: - jwt: [] parameters: - $ref: '#/components/parameters/namespaceTenantIDPath' requestBody: content: application/json: schema: type: object properties: username: description: Member's username. type: string role: $ref: '#/components/schemas/namespaceMemberRole' required: - username - role responses: '200': description: Success to add a member to a namespace. content: application/json: schema: $ref: '#/components/schemas/namespace' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '409': $ref: '#/components/responses/409' '500': $ref: '#/components/responses/500' /api/namespaces/{tenant}/members/{uid}: delete: operationId: removeNamespaceMember summary: Remove a member from a namespace description: Remove a member from a namespace. tags: - namespaces security: - jwt: [] parameters: - $ref: '#/components/parameters/namespaceTenantIDPath' - $ref: '#/components/parameters/namespaceMemberIDPath' responses: '200': description: Success to delete a member from namespace. content: application/json: schema: $ref: '#/components/schemas/namespace' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' patch: operationId: updateNamespaceMember summary: Update a member from a namespace description: Update a member role from a namespace. tags: - namespaces security: - jwt: [] parameters: - $ref: '#/components/parameters/namespaceTenantIDPath' - $ref: '#/components/parameters/namespaceMemberIDPath' requestBody: content: application/json: schema: type: object properties: role: $ref: '#/components/schemas/namespaceMemberRole' responses: '200': description: Success to update member role from a namespace. '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' /api/devices/{uid}/tags: parameters: - $ref: '#/components/parameters/deviceUIDPath' post: operationId: createDeviceTag summary: Create a tag description: Create a tag tags: - devices - tags security: - jwt: [] requestBody: content: application/json: schema: type: object properties: tag: $ref: '#/components/schemas/tag' required: - tag example: tag: tag1 responses: '200': description: Success create a tag '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '406': $ref: '#/components/responses/406' '409': $ref: '#/components/responses/409' '500': $ref: '#/components/responses/500' put: operationId: updateTagsDevice summary: Update tags to device description: Update tags to device tags: - devices - tags security: - jwt: [] requestBody: content: application/json: schema: properties: tags: description: Device's Tags list. $ref: '#/components/schemas/deviceTags' required: - tags responses: '200': description: Success to update tags to device '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '406': $ref: '#/components/responses/406' '500': $ref: '#/components/responses/500' /api/devices/{uid}/tags/{tag}: parameters: - $ref: '#/components/parameters/deviceUIDPath' - $ref: '#/components/parameters/deviceTagPath' delete: operationId: deleteDeviceTag summary: Delete a tag from device description: Delete a tag from device. tags: - devices - tags security: - jwt: [] responses: '200': description: Success to delete from device '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' /api/tags: get: operationId: getTags summary: Get tags tags: - tags security: - jwt: [] responses: '200': description: Success to get tag list. headers: X-Total-Count: description: Tags' total number. schema: type: string minimum: 0 content: application/json: schema: type: array items: type: string example: - tag1 - tag2 - tag3 - tag4 '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' /api/tags/{tag}: parameters: - name: tag description: Tag's name. schema: $ref: '#/components/schemas/tag' required: true in: path put: operationId: renameTag summary: Rename a tag name. tags: - tags security: - jwt: [] requestBody: content: application/json: schema: type: object properties: tag: description: New tag's name. $ref: '#/components/schemas/tag' required: - name responses: '200': description: Success to update a tag name. '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '409': $ref: '#/components/responses/409' '500': $ref: '#/components/responses/500' delete: operationId: deleteTag summary: Delete a tag name. tags: - tags security: - jwt: [] responses: '200': description: Success to delete a tag name. '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' /api/announcements: get: operationId: listAnnouncements summary: List announcements description: List the announcements posted by ShellHub Cloud. tags: - announcements servers: - url: https://cloud.shellhub.io description: ShellHub Cloud API server security: [] parameters: - $ref: '#/components/parameters/pageQuery' - $ref: '#/components/parameters/perPageQuery' - name: order_by schema: description: Announcements' list order. type: string enum: - asc - desc example: asc default: desc required: false in: query responses: '200': description: Success to get the announcements. headers: X-Total-Count: description: Announcements' total number. schema: type: string minimum: 0 readOnly: true content: application/json: schema: type: array items: $ref: '#/components/schemas/announcementShort' '400': $ref: '#/components/responses/400' '500': $ref: '#/components/responses/500' /api/announcements/{uuid}: get: operationId: getAnnouncement summary: Get a announcement description: Get a announcement. tags: - announcements servers: - url: https://cloud.shellhub.io description: ShellHub Cloud API server security: [] parameters: - $ref: '#/components/parameters/announcementUUID' responses: '200': description: Success to get a announcement. content: application/json: schema: $ref: '#/components/schemas/announcement' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500'