ShellHub Cloud OpenAPI (0.17.1)

Download OpenAPI specification:Download

E-mail: contato@ossystems.com.br License: Apache License 2.0

NOTICE: THE API IS NOT STABLE YET; ERROR AND INCONSISTENCIES MAY OCCUR.

ShellHub Cloud OpenAPI specification.

It documents all routes provided by ShellHub Cloud.

cloud

Routes provided by ShellHub Cloud API.

Get session recorded data

Get session recorded data.

Authorizations:

jwt

path Parameters

uid

required

string (sessionUID) ^[0-9a-f]{64}$

Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a

Session's UID

Responses

Response samples

200
401
500

Content type

application/json

[{"uid": "50d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacd0f6545c",
"message": "string",
"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"time": "2020-05-01T00:00:00.000Z",
"width": 24,
"height": 111
}
]

Close session

Close a session.

Authorizations:

jwt

path Parameters

uid

required

string (sessionUID) ^[0-9a-f]{64}$

Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a

Session's UID

Request Body schema: application/json

device

required

string (deviceUID) ^[0-9a-f]{64}$

Device's UID

Responses

Request samples

Payload

Content type

application/json

{"device": "13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a"
}

Response samples

500

Content type

application/json

{"message": "Internal Server Error"
}

Record session

Record data about session session.

Authorizations:

jwt

path Parameters

uid

required

string (sessionUID) ^[0-9a-f]{64}$

Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a

Session's UID

Request Body schema: application/json

uid required	string Session's UID.
message required	string Session's data.
width required	integer Session's pty width.
height required	integer Session's pty height.

Responses

Request samples

Payload

Content type

application/json

{"uid": "string",
"message": "string",
"width": 0,
"height": 0
}

Response samples

422
500

Content type

application/json

{"message": "string"
}

Create firewall rule

Create a firewall rule.

Authorizations:

jwt

Request Body schema: application/json

action required	string Enum: "allow" "deny" Firewall rule's action
active required	boolean Firewall rule active's status
required	object or object Firewall rule's filter
priority required	integer >= 0 Firewall rule's priority
source_ip required	string Firewall rule's source IP regexp
username required	string Firewall rule's username regexp

Responses

Request samples

Payload

Content type

application/json

{"action": "allow",
"active": true,
"filter": {"hostname": ".*"
},
"priority": 1,
"source_ip": ".*",
"username": ".*"
}

Response samples

200
401
500

Content type

application/json

{"id": "507f1f77bcf86cd799439011",
"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"action": "allow",
"active": true,
"filter": {"hostname": ".*"
},
"priority": 1,
"source_ip": ".*",
"username": ".*"
}

Get firewall rules

Get a list of firewall rules.

Authorizations:

jwt

query Parameters

page	integer >= 1 Default: 1 Page number
per_page	integer [ 1 .. 100 ] Default: 10 Items per page

Responses

Response samples

200
401
500

Content type

application/json

[{"id": "507f1f77bcf86cd799439011",
"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"action": "allow",
"active": true,
"filter": {"hostname": ".*"
},
"priority": 1,
"source_ip": ".*",
"username": ".*"
}
]

Get firewall rule

Get a firewall rule.

Authorizations:

jwt

path Parameters

id

required

integer

Firewall rule's ID

Responses

Response samples

200
401
500

Content type

application/json

{"id": "507f1f77bcf86cd799439011",
"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"action": "allow",
"active": true,
"filter": {"hostname": ".*"
},
"priority": 1,
"source_ip": ".*",
"username": ".*"
}

Update firewall rule

Update a firewall rule.

Authorizations:

jwt

path Parameters

id

required

integer

Firewall rule's ID

Request Body schema: application/json

action required	string Enum: "allow" "deny" Firewall rule's action
active required	boolean Firewall rule active's status
required	object or object Firewall rule's filter
priority required	integer >= 0 Firewall rule's priority
source_ip required	string Firewall rule's source IP regexp
username required	string Firewall rule's username regexp

Responses

Request samples

Payload

Content type

application/json

{"action": "allow",
"active": true,
"filter": {"hostname": ".*"
},
"priority": 1,
"source_ip": ".*",
"username": ".*"
}

Response samples

200
401
500

Content type

application/json

{"id": "507f1f77bcf86cd799439011",
"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"action": "allow",
"active": true,
"filter": {"hostname": ".*"
},
"priority": 1,
"source_ip": ".*",
"username": ".*"
}

Delete firewall rule

Delete a firewall rule.

Authorizations:

jwt

path Parameters

id

required

integer

Firewall rule's ID

Responses

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Add a tag to firewall rule

Authorizations:

jwt

path Parameters

id

required

string

Firewall rule's ID

Request Body schema: application/json

tag

required

string

Responses

Request samples

Payload

Content type

application/json

{"tag": "tag1"
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Remove a tag from firewall rule

Authorizations:

jwt

path Parameters

id

required

string

Firewall rule's ID

Request Body schema: application/json

tag

required

string

Responses

Request samples

Payload

Content type

application/json

{"tag": "tag1"
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Update tags in firewall rule

Authorizations:

jwt

path Parameters

id

required

string

Firewall rule's ID

Request Body schema: application/json

tags

required

Array of strings [ 1 .. 3 ] items

Responses

Request samples

Payload

Content type

application/json

{"tags": ["tag1",
"tag2",
"tag3"
]
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Register a new user

Request Body schema: application/json

name required	string The full name of the user.
email required	string The user's email address, which must be unique. This email will be used for login and for receiving important notifications, such as password reset emails. If `email_marketing` is set to `true`, promotional emails will also be sent to this address.
username required	string The username, which must be unique across the system. Users can log in using either their username or email.
password required	string <^([a-zA-Z0-9_-]){1,64}$> The password for the user account. Must follow the regex.
email_marketing required	boolean Indicates whether the user opts to receive marketing and promotional emails.
sig	string For standard registration processes, this field should be ignored. A unique signature included in an invitation email. This is used to automatically confirm the user's registration without requiring an additional confirmation email.

Responses

Request samples

Payload

Content type

application/json

{"name": "John Doe",
"email": "john.doe@test.com",
"username": "john_doe",
"password": "mS@aZ%n267M@3&k!H46^#78s!@$F4^@7",
"email_marketing": true,
"sig": ""
}

Response samples

400
401
409
500

Content type

application/json

["username",
"email"
]

Resend confirmation

Resend confirmation to user.

Request Body schema: application/json

username

required

string [ 3 .. 20 ] characters

User's username.

Responses

Request samples

Payload

Content type

application/json

{"username": "example"
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Update user password

Update user password from a recovery token got from email.

path Parameters

uid

required

string

Example: 507f1f77bcf86cd799439011

User's UID.

Request Body schema: application/json

password required	string (userPassword) [ 5 .. 30 ] characters User's password.
token required	string User's recovery token. It is the token from the email sent to user when the user request password reset.

Responses

Request samples

Payload

Content type

application/json

{"password": "example",
"token": "3dd0d1f8-8246-4519-b11a-a3dd33717f65"
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Validate activation link

Validate the activation link for user.

query Parameters

email required	string <email> Example: email=example@example.com User's email.
token required	string Example: token=3dd0d1f8-8246-4519-b11a-a3dd33717f65 User's validation token. It is a token received from the email used to validate the user.

Responses

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Recover password

Send a recovery email to the user.

Request Body schema: application/json

required	userUsername (string) or userEmail (string)
One of [ 3 .. 30 ] characters string (userUsername) [ 3 .. 30 ] characters ^[a-zA-Z0-9-_.@]{3,30}$ User's username.

Responses

Request samples

Payload

Content type

application/json

{"username": "example"
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Create customer

creates a new customer defining, optionaly, the default payment method.

Authorizations:

jwt

Responses

Response samples

Content type

application/json

{"message": "string",
"code": "string"
}

Get Customer

Get the customer.

Authorizations:

jwt

Responses

Response samples

Content type

application/json

{"id": "cus_H9J5n2eZvKYlo2C7X1QX2Qg",
"name": "user",
"email": "user@shellhub.io",
"payment_methods": [{"id": "pm_1H9J5n2eZvKYlo2C7X1QX2Qg",
"number": "4242424242424242",
"brand": "visa",
"exp_month": 10,
"exp_year": 2030,
"cvc": "123",
"default": true
}
]
}

Create subscription

Create a subscription.

Authorizations:

jwt

Responses

Response samples

Content type

application/json

{"message": "string",
"code": "string"
}

Get subscription

Get the subscription.

Authorizations:

jwt

Responses

Response samples

Content type

application/json

{"id": "sub_H9J5n2eZvKYlo2C7X1QX2Qg",
"active": true,
"status": "active",
"end_at": 31536000,
"invoices": [{"id": "in_H9J5n2eZvKYlo2C7X1QX2Qg",
"status": "open",
"currency": "usd",
"amount": 0
}
]
}

Attach payment method

Attachs a payment method to a customer.

Authorizations:

jwt

Request Body schema: application/json

id

required

string

Payment method's ID.

Responses

Request samples

Payload

Content type

application/json

{"id": "pm_H9J5n2eZvKYlo2C7X1QX2Qg"
}

Response samples

Content type

application/json

{"message": "string",
"code": "string"
}

Detach payment method

Detachs a payment method from a customer.

Authorizations:

jwt

Request Body schema: application/json

id

required

string

Payment method's ID.

Responses

Request samples

Payload

Content type

application/json

{"id": "pm_H9J5n2eZvKYlo2C7X1QX2Qg"
}

Response samples

Content type

application/json

{"message": "string",
"code": "string"
}

Set default payment method

Set default payment method to the customer.

Authorizations:

jwt

Request Body schema: application/json

id

required

string

Payment method's ID.

Responses

Request samples

Payload

Content type

application/json

{"id": "pm_H9J5n2eZvKYlo2C7X1QX2Qg"
}

Response samples

Content type

application/json

{"message": "string",
"code": "string"
}

Choice devices

Choice devices when device's limit is rechead.

Authorizations:

jwt

Request Body schema: application/json

choices

required

Array of strings[ items [ 0 .. 3 ] items ]

Device's list.

Responses

Request samples

Payload

Content type

application/json

{"choices": ["string"
]
}

Response samples

500

Content type

application/json

{"message": "Internal Server Error"
}

Get devices most used

Get the most used devices.

Authorizations:

jwt

Responses

Response samples

200
500

Content type

application/json

[{"uid": "13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a",
"name": "example",
"identity": {"mac": "00:00:00:00:00:00"
},
"info": {"id": "example",
"pretty_name": "linux",
"version": "latest",
"arch": "x86_64",
"platform": "docker"
},
"public_key": "-----BEGIN RSA PUBLIC KEY-----MIIBCgKCAQEA0vH2Bob3mn+uWVaHlOoZD8ai01W6VnRTnXlnHVF7Ny1Vb7pl1Hc4D8bsBhb1vt7aZOYHbCyDR2r5lsrWXCELE8pY8vzfFDA+jNrLbBCJ66E1BcmTqfXCJcLospWD2lIAwU2O7IPxwZujuVkHrF8nYuEFsKeG60QTWNS++RTqydqe2KmFMEdWCQmYPm/ykN871fSR9+PzoRJMYWidY6Szn+X2ardGmS/Ldhl/PEu9h7xjcQXANWz6yV/RVReGVkLcK6TxlfuxgdpbsWAx+cS52P7xWrshNefHqjpdlm3KNbo6vqfTpU8Ld/FFISXXaa1Md5GyAHF+jzuRzQ5z5aKBGwIDAQAB-----END RSA PUBLIC KEY-----",
"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"last_seen": "2020-01-01T00:00:00Z",
"online": true,
"namespace": "examplespace",
"status": "accepted",
"status_update_at": "2020-05-01T00:00:00.000Z",
"created_at": "2020-01-01T00:00:00Z",
"remote_addr": "127.0.0.1",
"position": {"latitude": -31.7566628,
"longitude": -52.322474
},
"tags": ["tag1",
"tag2",
"tag3"
],
"public_url": false,
"acceptable": false
}
]

Report

Report an action.

Authorizations:

jwt

query Parameters

action

required

string

Enum: "device_accept" "namespace_delete"

Responses

Response samples

Content type

application/json

"string"

Evaluate

evaluate the namespace capabilities.

Authorizations:

jwt

Responses

Response samples

Content type

application/json

{"can_accept": false,
"can_connect": true
}

Auth MFA

Authenticate a user who has MFA enabled. This endpoint should be called after the default authUser endpoint, which generates an X-MFA-Token indicating that the user has already authenticated with a password.

Request Body schema: application/json

token required	string The `X-MFA-Token` header returned by the authUser endpoint.
code required	string The current code from the MFA authenticator.

Responses

Request samples

Payload

Content type

application/json

{"token": "bf265bf8-0065-4f44-a3ac-55eb3134c6ec",
"code": "123456"
}

Response samples

200
401
500

Content type

application/json

{"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJleGFtcGxlIiwibmFtZSI6ImV4YW1wbGUiLCJpYXQiOjE1MTYyMzkwMjJ9.zqCt70KspnNnitZlv89hDbFZ5iGMMRUn0wFEmmlY-to",
"id": "507f1f77bcf86cd799439011",
"user": "example",
"name": "example",
"email": "example@example.com",
"recovery_email": "user@example.com",
"tenant": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"role": "administrator",
"mfa": false,
"max_namespaces": 3
}

Recover MFA

Recover account access by providing one of the user's recovery codes. It will be invalidated for future uses.

The recovery code will be cached for 10 minutes. During this period, the user can use the same recovery code to disable their MFA without needing to provide two separate codes. The X-Expires-At header specifies the epoch value marking the end of the cache period.

Request Body schema: application/json

identifier required	string The same as the login identifier; can be either the user's email or username.
recovery_code required	string One of the user's recovery codes.

Responses

Request samples

Payload

Content type

application/json

{"identifier": "john_doe",
"recovery_code": "6DIGYYGM3JM7GXC4"
}

Response samples

200
401
500

Content type

application/json

{"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJleGFtcGxlIiwibmFtZSI6ImV4YW1wbGUiLCJpYXQiOjE1MTYyMzkwMjJ9.zqCt70KspnNnitZlv89hDbFZ5iGMMRUn0wFEmmlY-to",
"id": "507f1f77bcf86cd799439011",
"user": "example",
"name": "example",
"email": "example@example.com",
"recovery_email": "user@example.com",
"tenant": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"role": "administrator",
"mfa": false,
"max_namespaces": 3
}

Request Reset MFA

Sends an email to both the user's main and recovery addresses. Each email contains a unique code, which remains valid for at most 1 day. The user must provide both codes to reset their MFA.

Request Body schema: application/json

identifier

required

string

The same as the login identifier; can be either the user's email or username.

Responses

Request samples

Payload

Content type

application/json

{"identifier": "john_doe"
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Generate MFA Credentials

Generate the credentials to enable a user's MFA. The user must save the recovery codes a secure manner.

Authorizations:

jwt

Responses

Response samples

200
401
500

Content type

application/json

{"link": "otpauth://totp/shellhub-enterprise:662ba312616a7bdb5a2b608d?issuer=shellhub-enterprise&secret=TWBIH44WRHW44B773HJSG3RNZXH4KWSD",
"secret": "TWBIH44WRHW44B773HJSG3RNZXH4KWSD",
"recovery_codes": [["MLNSPOB2L2ZRO2D5",
"35QBUON4JAA4V6KP",
"UYH34OY5RNDRRSUS",
"IBWGL3IN42LTS3PP",
"6DIGYYGM3JM7GXC4",
"6UIHAIN3CYUEFY5X"
]
]
}

Enable MFA

Enable MFA for a user. The secret and recovery codes must be created by the generateMFA endpoint. Users with MFA already enabled cannot override their MFA credentials; in these cases, a user must disable MFA before proceeding. The recovery e-mail must be a valid value in order to enable the MFA.

Authorizations:

jwt

Request Body schema: application/json

code required	string The code generated by the MFA app.
secret required	string The secret generated by generateMFA endpoint.
recovery_codes required	Array of strings A list of codes generated by generateMFA endpoint. These codes can be used when a user loses their MFA app.

Responses

Request samples

Payload

Content type

application/json

{"code": "123456",
"secret": "TWBIH44WRHW44B773HJSG3RNZXH4KWSD",
"recovery_codes": [["MLNSPOB2L2ZRO2D5",
"35QBUON4JAA4V6KP",
"UYH34OY5RNDRRSUS",
"IBWGL3IN42LTS3PP",
"6DIGYYGM3JM7GXC4",
"6UIHAIN3CYUEFY5X"
]
]
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Disable MFA

Disable MFA for a user. To disable MFA, the user must provide either a recovery code or the current MFA code. If a recovery code is used, it will be invalidated for future use.

The recovery code used to regain access to the account can be used within a 10-minute window on this endpoint.

Authorizations:

jwt

Request Body schema: application/json

code	string The code generated by the MFA app.
recovery_code	string User's recovery code.

Responses

Request samples

Payload

Content type

application/json

{"code": "123456",
"recovery_code": "6UIHAIN3CYUEFY5X"
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Reset MFA

Similar to the disableMFA operation, this endpoint uses the two codes sent by requestResetMFA instead of a TOTP or recovery code. The user ID must be the same as the one used for requestResetMFA.

path Parameters

user-id

string

Example: 664e02087116dc765ef876a0

ID of the user trying to reset MFA.

Request Body schema: application/json

main_email_code required	string The code sent to the main email address.
recovery_email_code required	string The code sent to the recovery email address.

Responses

Request samples

Payload

Content type

application/json

{"main_email_code": "JR36Q",
"recovery_email_code": "AB2D8"
}

Response samples

200
401
500

Content type

application/json

{"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJleGFtcGxlIiwibmFtZSI6ImV4YW1wbGUiLCJpYXQiOjE1MTYyMzkwMjJ9.zqCt70KspnNnitZlv89hDbFZ5iGMMRUn0wFEmmlY-to",
"id": "507f1f77bcf86cd799439011",
"user": "example",
"name": "example",
"email": "example@example.com",
"recovery_email": "user@example.com",
"tenant": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"role": "administrator",
"mfa": false,
"max_namespaces": 3
}

Delete user

Deletes the authenticated user. The user will be removed from any namespaces they are a member of. Users who are owners of namespaces cannot be deleted. In such cases, the user must delete the namespace(s) first.

NOTE: This route is available only for cloud instances. Enterprise users must use the admin console, and community users must use the CLI.

Authorizations:

jwt

Responses

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

sessions

Routes related to session resource.

Get session recorded data

Get session recorded data.

Authorizations:

jwt

path Parameters

uid

required

string (sessionUID) ^[0-9a-f]{64}$

Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a

Session's UID

Responses

Response samples

200
401
500

Content type

application/json

[{"uid": "50d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacd0f6545c",
"message": "string",
"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"time": "2020-05-01T00:00:00.000Z",
"width": 24,
"height": 111
}
]

Close session

Close a session.

Authorizations:

jwt

path Parameters

uid

required

string (sessionUID) ^[0-9a-f]{64}$

Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a

Session's UID

Request Body schema: application/json

device

required

string (deviceUID) ^[0-9a-f]{64}$

Device's UID

Responses

Request samples

Payload

Content type

application/json

{"device": "13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a"
}

Response samples

500

Content type

application/json

{"message": "Internal Server Error"
}

Record session

Record data about session session.

Authorizations:

jwt

path Parameters

uid

required

string (sessionUID) ^[0-9a-f]{64}$

Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a

Session's UID

Request Body schema: application/json

uid required	string Session's UID.
message required	string Session's data.
width required	integer Session's pty width.
height required	integer Session's pty height.

Responses

Request samples

Payload

Content type

application/json

{"uid": "string",
"message": "string",
"width": 0,
"height": 0
}

Response samples

422
500

Content type

application/json

{"message": "string"
}

Set session record

Define if sessions will be recorded.

Authorizations:

jwt

path Parameters

tenant

required

string <uuid> (namespaceTenantID)

Example: 3dd0d1f8-8246-4519-b11a-a3dd33717f65

Namespace's tenant ID

Request Body schema: application/json

session_record

boolean

Default: false

Session's record status.

Responses

Request samples

Payload

Content type

application/json

{"session_record": false
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Get session record

Get status from if session record feature is enable.

Authorizations:

jwt

Responses

Response samples

200
401
500

Content type

application/json

true

Get sessions

Get a list sessions.

Authorizations:

jwt

query Parameters

page	integer >= 1 Default: 1 Page number
per_page	integer [ 1 .. 100 ] Default: 10 Items per page

Responses

Response samples

200
401
500

Content type

application/json

[{"uid": "13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a",
"device_uid": "13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a",
"device": {"uid": "13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a",
"name": "example",
"identity": {"mac": "00:00:00:00:00:00"
},
"info": {"id": "example",
"pretty_name": "linux",
"version": "latest",
"arch": "x86_64",
"platform": "docker"
},
"public_key": "-----BEGIN RSA PUBLIC KEY-----MIIBCgKCAQEA0vH2Bob3mn+uWVaHlOoZD8ai01W6VnRTnXlnHVF7Ny1Vb7pl1Hc4D8bsBhb1vt7aZOYHbCyDR2r5lsrWXCELE8pY8vzfFDA+jNrLbBCJ66E1BcmTqfXCJcLospWD2lIAwU2O7IPxwZujuVkHrF8nYuEFsKeG60QTWNS++RTqydqe2KmFMEdWCQmYPm/ykN871fSR9+PzoRJMYWidY6Szn+X2ardGmS/Ldhl/PEu9h7xjcQXANWz6yV/RVReGVkLcK6TxlfuxgdpbsWAx+cS52P7xWrshNefHqjpdlm3KNbo6vqfTpU8Ld/FFISXXaa1Md5GyAHF+jzuRzQ5z5aKBGwIDAQAB-----END RSA PUBLIC KEY-----",
"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"last_seen": "2020-01-01T00:00:00Z",
"online": true,
"namespace": "examplespace",
"status": "accepted",
"status_update_at": "2020-05-01T00:00:00.000Z",
"created_at": "2020-01-01T00:00:00Z",
"remote_addr": "127.0.0.1",
"position": {"latitude": -31.7566628,
"longitude": -52.322474
},
"tags": ["tag1",
"tag2",
"tag3"
],
"public_url": false,
"acceptable": false
},
"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"username": "string",
"ip_address": "127.0.0.1",
"started_at": "2020-01-01T00:00:00Z",
"last_seen": "2020-01-01T00:00:00Z",
"active": true,
"authenticated": true,
"recorded": true,
"type": "web",
"term": "xterm.js",
"position": {"latitude": -31.7566628,
"longitude": -52.322474
}
}
]

Get session

Get a session.

Authorizations:

jwt

path Parameters

uid

required

string (sessionUID) ^[0-9a-f]{64}$

Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a

Session's UID

Responses

Response samples

200
401
500

Content type

application/json

{"uid": "13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a",
"device_uid": "13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a",
"device": {"uid": "13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a",
"name": "example",
"identity": {"mac": "00:00:00:00:00:00"
},
"info": {"id": "example",
"pretty_name": "linux",
"version": "latest",
"arch": "x86_64",
"platform": "docker"
},
"public_key": "-----BEGIN RSA PUBLIC KEY-----MIIBCgKCAQEA0vH2Bob3mn+uWVaHlOoZD8ai01W6VnRTnXlnHVF7Ny1Vb7pl1Hc4D8bsBhb1vt7aZOYHbCyDR2r5lsrWXCELE8pY8vzfFDA+jNrLbBCJ66E1BcmTqfXCJcLospWD2lIAwU2O7IPxwZujuVkHrF8nYuEFsKeG60QTWNS++RTqydqe2KmFMEdWCQmYPm/ykN871fSR9+PzoRJMYWidY6Szn+X2ardGmS/Ldhl/PEu9h7xjcQXANWz6yV/RVReGVkLcK6TxlfuxgdpbsWAx+cS52P7xWrshNefHqjpdlm3KNbo6vqfTpU8Ld/FFISXXaa1Md5GyAHF+jzuRzQ5z5aKBGwIDAQAB-----END RSA PUBLIC KEY-----",
"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"last_seen": "2020-01-01T00:00:00Z",
"online": true,
"namespace": "examplespace",
"status": "accepted",
"status_update_at": "2020-05-01T00:00:00.000Z",
"created_at": "2020-01-01T00:00:00Z",
"remote_addr": "127.0.0.1",
"position": {"latitude": -31.7566628,
"longitude": -52.322474
},
"tags": ["tag1",
"tag2",
"tag3"
],
"public_url": false,
"acceptable": false
},
"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"username": "string",
"ip_address": "127.0.0.1",
"started_at": "2020-01-01T00:00:00Z",
"last_seen": "2020-01-01T00:00:00Z",
"active": true,
"authenticated": true,
"recorded": true,
"type": "web",
"term": "xterm.js",
"position": {"latitude": -31.7566628,
"longitude": -52.322474
}
}

Set session authentication status

Set session authentication status.

Authorizations:

jwt

path Parameters

uid

required

string (sessionUID) ^[0-9a-f]{64}$

Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a

Session's UID

Request Body schema: application/json

authenticated

boolean

Session's authentication status.

Responses

Request samples

Payload

Content type

application/json

{"authenticated": true
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

users

Routes related to users resource.

Register a new user

Request Body schema: application/json

name required	string The full name of the user.
email required	string The user's email address, which must be unique. This email will be used for login and for receiving important notifications, such as password reset emails. If `email_marketing` is set to `true`, promotional emails will also be sent to this address.
username required	string The username, which must be unique across the system. Users can log in using either their username or email.
password required	string <^([a-zA-Z0-9_-]){1,64}$> The password for the user account. Must follow the regex.
email_marketing required	boolean Indicates whether the user opts to receive marketing and promotional emails.
sig	string For standard registration processes, this field should be ignored. A unique signature included in an invitation email. This is used to automatically confirm the user's registration without requiring an additional confirmation email.

Responses

Request samples

Payload

Content type

application/json

{"name": "John Doe",
"email": "john.doe@test.com",
"username": "john_doe",
"password": "mS@aZ%n267M@3&k!H46^#78s!@$F4^@7",
"email_marketing": true,
"sig": ""
}

Response samples

400
401
409
500

Content type

application/json

["username",
"email"
]

Resend confirmation

Resend confirmation to user.

Request Body schema: application/json

username

required

string [ 3 .. 20 ] characters

User's username.

Responses

Request samples

Payload

Content type

application/json

{"username": "example"
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Update user password

Update user password from a recovery token got from email.

path Parameters

uid

required

string

Example: 507f1f77bcf86cd799439011

User's UID.

Request Body schema: application/json

password required	string (userPassword) [ 5 .. 30 ] characters User's password.
token required	string User's recovery token. It is the token from the email sent to user when the user request password reset.

Responses

Request samples

Payload

Content type

application/json

{"password": "example",
"token": "3dd0d1f8-8246-4519-b11a-a3dd33717f65"
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Validate activation link

Validate the activation link for user.

query Parameters

email required	string <email> Example: email=example@example.com User's email.
token required	string Example: token=3dd0d1f8-8246-4519-b11a-a3dd33717f65 User's validation token. It is a token received from the email used to validate the user.

Responses

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Recover password

Send a recovery email to the user.

Request Body schema: application/json

required	userUsername (string) or userEmail (string)
One of [ 3 .. 30 ] characters string (userUsername) [ 3 .. 30 ] characters ^[a-zA-Z0-9-_.@]{3,30}$ User's username.

Responses

Request samples

Payload

Content type

application/json

{"username": "example"
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Auth MFA

Authenticate a user who has MFA enabled. This endpoint should be called after the default authUser endpoint, which generates an X-MFA-Token indicating that the user has already authenticated with a password.

Request Body schema: application/json

token required	string The `X-MFA-Token` header returned by the authUser endpoint.
code required	string The current code from the MFA authenticator.

Responses

Request samples

Payload

Content type

application/json

{"token": "bf265bf8-0065-4f44-a3ac-55eb3134c6ec",
"code": "123456"
}

Response samples

200
401
500

Content type

application/json

{"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJleGFtcGxlIiwibmFtZSI6ImV4YW1wbGUiLCJpYXQiOjE1MTYyMzkwMjJ9.zqCt70KspnNnitZlv89hDbFZ5iGMMRUn0wFEmmlY-to",
"id": "507f1f77bcf86cd799439011",
"user": "example",
"name": "example",
"email": "example@example.com",
"recovery_email": "user@example.com",
"tenant": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"role": "administrator",
"mfa": false,
"max_namespaces": 3
}

Recover MFA

Recover account access by providing one of the user's recovery codes. It will be invalidated for future uses.

The recovery code will be cached for 10 minutes. During this period, the user can use the same recovery code to disable their MFA without needing to provide two separate codes. The X-Expires-At header specifies the epoch value marking the end of the cache period.

Request Body schema: application/json

identifier required	string The same as the login identifier; can be either the user's email or username.
recovery_code required	string One of the user's recovery codes.

Responses

Request samples

Payload

Content type

application/json

{"identifier": "john_doe",
"recovery_code": "6DIGYYGM3JM7GXC4"
}

Response samples

200
401
500

Content type

application/json

{"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJleGFtcGxlIiwibmFtZSI6ImV4YW1wbGUiLCJpYXQiOjE1MTYyMzkwMjJ9.zqCt70KspnNnitZlv89hDbFZ5iGMMRUn0wFEmmlY-to",
"id": "507f1f77bcf86cd799439011",
"user": "example",
"name": "example",
"email": "example@example.com",
"recovery_email": "user@example.com",
"tenant": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"role": "administrator",
"mfa": false,
"max_namespaces": 3
}

Request Reset MFA

Sends an email to both the user's main and recovery addresses. Each email contains a unique code, which remains valid for at most 1 day. The user must provide both codes to reset their MFA.

Request Body schema: application/json

identifier

required

string

The same as the login identifier; can be either the user's email or username.

Responses

Request samples

Payload

Content type

application/json

{"identifier": "john_doe"
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Enable MFA

Enable MFA for a user. The secret and recovery codes must be created by the generateMFA endpoint. Users with MFA already enabled cannot override their MFA credentials; in these cases, a user must disable MFA before proceeding. The recovery e-mail must be a valid value in order to enable the MFA.

Authorizations:

jwt

Request Body schema: application/json

code required	string The code generated by the MFA app.
secret required	string The secret generated by generateMFA endpoint.
recovery_codes required	Array of strings A list of codes generated by generateMFA endpoint. These codes can be used when a user loses their MFA app.

Responses

Request samples

Payload

Content type

application/json

{"code": "123456",
"secret": "TWBIH44WRHW44B773HJSG3RNZXH4KWSD",
"recovery_codes": [["MLNSPOB2L2ZRO2D5",
"35QBUON4JAA4V6KP",
"UYH34OY5RNDRRSUS",
"IBWGL3IN42LTS3PP",
"6DIGYYGM3JM7GXC4",
"6UIHAIN3CYUEFY5X"
]
]
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Disable MFA

Disable MFA for a user. To disable MFA, the user must provide either a recovery code or the current MFA code. If a recovery code is used, it will be invalidated for future use.

The recovery code used to regain access to the account can be used within a 10-minute window on this endpoint.

Authorizations:

jwt

Request Body schema: application/json

code	string The code generated by the MFA app.
recovery_code	string User's recovery code.

Responses

Request samples

Payload

Content type

application/json

{"code": "123456",
"recovery_code": "6UIHAIN3CYUEFY5X"
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Reset MFA

Similar to the disableMFA operation, this endpoint uses the two codes sent by requestResetMFA instead of a TOTP or recovery code. The user ID must be the same as the one used for requestResetMFA.

path Parameters

user-id

string

Example: 664e02087116dc765ef876a0

ID of the user trying to reset MFA.

Request Body schema: application/json

main_email_code required	string The code sent to the main email address.
recovery_email_code required	string The code sent to the recovery email address.

Responses

Request samples

Payload

Content type

application/json

{"main_email_code": "JR36Q",
"recovery_email_code": "AB2D8"
}

Response samples

200
401
500

Content type

application/json

{"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJleGFtcGxlIiwibmFtZSI6ImV4YW1wbGUiLCJpYXQiOjE1MTYyMzkwMjJ9.zqCt70KspnNnitZlv89hDbFZ5iGMMRUn0wFEmmlY-to",
"id": "507f1f77bcf86cd799439011",
"user": "example",
"name": "example",
"email": "example@example.com",
"recovery_email": "user@example.com",
"tenant": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"role": "administrator",
"mfa": false,
"max_namespaces": 3
}

Delete user

Deletes the authenticated user. The user will be removed from any namespaces they are a member of. Users who are owners of namespaces cannot be deleted. In such cases, the user must delete the namespace(s) first.

NOTE: This route is available only for cloud instances. Enterprise users must use the admin console, and community users must use the CLI.

Authorizations:

jwt

Responses

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Accept a membership invite

This route is intended to be accessed directly through the link sent in the invitation email. The user must be logged into the account that was invited.

Authorizations:

jwt

path Parameters

tenant

required

string <uuid> (namespaceTenantID)

Example: 3dd0d1f8-8246-4519-b11a-a3dd33717f65

Namespace's tenant ID

Request Body schema: application/json

sig

required

string

The unique key included in the email link.

Responses

Request samples

Payload

Content type

application/json

{"sig": "b25e93bc-22ac-4f02-901a-52af9f358a5d"
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Login

Authenticate a user, returning the session's JWT token and user data.

Authentication may result in an account lockout after N consecutive incorrect login attempts. The lockout applies specifically to a particular source and user combination. Check for the presence of the X-Account-Lockout header to determine the account lockout status. When it's 0, there are no active lockouts.

Users with MFA enabled cannot authenticate via this route. In such cases, the API will respond with a status 401 and an X-MFA-Token header with a UUID. Authentication must be med to /api/mfa/auth with this token in these instances.

Request Body schema: application/json

username required	string (userUsername) [ 3 .. 30 ] characters ^[a-zA-Z0-9-_.@]{3,30}$ User's username.
password required	string (userPassword) [ 5 .. 30 ] characters User's password.

Responses

Request samples

Payload

Content type

application/json

{"username": "example",
"password": "example"
}

Response samples

200
500

Content type

application/json

{"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJleGFtcGxlIiwibmFtZSI6ImV4YW1wbGUiLCJpYXQiOjE1MTYyMzkwMjJ9.zqCt70KspnNnitZlv89hDbFZ5iGMMRUn0wFEmmlY-to",
"id": "507f1f77bcf86cd799439011",
"user": "example",
"name": "example",
"email": "example@example.com",
"recovery_email": "user@example.com",
"tenant": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"role": "administrator",
"mfa": false,
"max_namespaces": 3
}

Auth a user

Authenticate a user, returning the session's JWT token and data about the user.

Request Body schema: application/json

username required	string (userUsername) [ 3 .. 30 ] characters ^[a-zA-Z0-9-_.@]{3,30}$ User's username.
password required	string (userPassword) [ 5 .. 30 ] characters User's password.

Responses

Request samples

Payload

Content type

application/json

{"username": "example",
"password": "example"
}

Response samples

200
401
500

Content type

application/json

{"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJleGFtcGxlIiwibmFtZSI6ImV4YW1wbGUiLCJpYXQiOjE1MTYyMzkwMjJ9.zqCt70KspnNnitZlv89hDbFZ5iGMMRUn0wFEmmlY-to",
"id": "507f1f77bcf86cd799439011",
"user": "example",
"name": "example",
"email": "example@example.com",
"recovery_email": "user@example.com",
"tenant": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"role": "administrator",
"mfa": false,
"max_namespaces": 3
}

Get user info

Authorizations:

jwt

Responses

Response samples

200
401
500

Content type

application/json

{"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJleGFtcGxlIiwibmFtZSI6ImV4YW1wbGUiLCJpYXQiOjE1MTYyMzkwMjJ9.zqCt70KspnNnitZlv89hDbFZ5iGMMRUn0wFEmmlY-to",
"id": "507f1f77bcf86cd799439011",
"user": "example",
"name": "example",
"email": "example@example.com",
"recovery_email": "user@example.com",
"tenant": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"role": "administrator",
"mfa": false,
"max_namespaces": 3
}

Get token

Get a token from its tenant.

Authorizations:

jwt

path Parameters

tenant

string

Tenant

Responses

Response samples

200
401
500

Content type

application/json

{"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJleGFtcGxlIiwibmFtZSI6ImV4YW1wbGUiLCJpYXQiOjE1MTYyMzkwMjJ9.zqCt70KspnNnitZlv89hDbFZ5iGMMRUn0wFEmmlY-to",
"id": "507f1f77bcf86cd799439011",
"user": "example",
"name": "example",
"email": "example@example.com",
"recovery_email": "user@example.com",
"tenant": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"role": "administrator",
"mfa": false,
"max_namespaces": 3
}

Update user

Authorizations:

jwt

Request Body schema: application/json

name	string
username	string
email	string
recovery_email	string A recovery email serves as the user's final recourse to regain access to their account. It cannot be the same as the user's primary email. Once defined, it cannot be updated to an empty value.
password	string
current_password	string It's required when updating the user's password.

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"username": "string",
"email": "string",
"recovery_email": "string",
"password": "string",
"current_password": "string"
}

Response samples

400
401
409
500

Content type

application/json

["username",
"email"
]

Update user data Deprecated

Update user's data.

Authorizations:

jwt

path Parameters

id

required

string

User's ID.

Request Body schema: application/json

name	string User's name.
username	string User's username.
email	string <email> User's e-mail.
recovery_email	string <email> User's recovery e-mail. A recovery email serves as the user's final recourse to regain access to their account.

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"username": "string",
"email": "user@example.com",
"recovery_email": "user@example.com"
}

Response samples

400
401
409
500

Content type

application/json

["username",
"email"
]

Update user password Deprecated

Update only the user password.

Authorizations:

jwt

path Parameters

id	string User ID

Request Body schema: application/json

current_password	string User current password
new_password	string User new password

Responses

Request samples

Payload

Content type

application/json

{"current_password": "string",
"new_password": "string"
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Set session record

Define if sessions will be recorded.

Authorizations:

jwt

path Parameters

tenant

required

string <uuid> (namespaceTenantID)

Example: 3dd0d1f8-8246-4519-b11a-a3dd33717f65

Namespace's tenant ID

Request Body schema: application/json

session_record

boolean

Default: false

Session's record status.

Responses

Request samples

Payload

Content type

application/json

{"session_record": false
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Get session record

Get status from if session record feature is enable.

Authorizations:

jwt

Responses

Response samples

200
401
500

Content type

application/json

true

rules

Routes related to firewall rules resource

Create firewall rule

Create a firewall rule.

Authorizations:

jwt

Request Body schema: application/json

action required	string Enum: "allow" "deny" Firewall rule's action
active required	boolean Firewall rule active's status
required	object or object Firewall rule's filter
priority required	integer >= 0 Firewall rule's priority
source_ip required	string Firewall rule's source IP regexp
username required	string Firewall rule's username regexp

Responses

Request samples

Payload

Content type

application/json

{"action": "allow",
"active": true,
"filter": {"hostname": ".*"
},
"priority": 1,
"source_ip": ".*",
"username": ".*"
}

Response samples

200
401
500

Content type

application/json

{"id": "507f1f77bcf86cd799439011",
"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"action": "allow",
"active": true,
"filter": {"hostname": ".*"
},
"priority": 1,
"source_ip": ".*",
"username": ".*"
}

Get firewall rules

Get a list of firewall rules.

Authorizations:

jwt

query Parameters

page	integer >= 1 Default: 1 Page number
per_page	integer [ 1 .. 100 ] Default: 10 Items per page

Responses

Response samples

200
401
500

Content type

application/json

[{"id": "507f1f77bcf86cd799439011",
"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"action": "allow",
"active": true,
"filter": {"hostname": ".*"
},
"priority": 1,
"source_ip": ".*",
"username": ".*"
}
]

Get firewall rule

Get a firewall rule.

Authorizations:

jwt

path Parameters

id

required

integer

Firewall rule's ID

Responses

Response samples

200
401
500

Content type

application/json

{"id": "507f1f77bcf86cd799439011",
"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"action": "allow",
"active": true,
"filter": {"hostname": ".*"
},
"priority": 1,
"source_ip": ".*",
"username": ".*"
}

Update firewall rule

Update a firewall rule.

Authorizations:

jwt

path Parameters

id

required

integer

Firewall rule's ID

Request Body schema: application/json

action required	string Enum: "allow" "deny" Firewall rule's action
active required	boolean Firewall rule active's status
required	object or object Firewall rule's filter
priority required	integer >= 0 Firewall rule's priority
source_ip required	string Firewall rule's source IP regexp
username required	string Firewall rule's username regexp

Responses

Request samples

Payload

Content type

application/json

{"action": "allow",
"active": true,
"filter": {"hostname": ".*"
},
"priority": 1,
"source_ip": ".*",
"username": ".*"
}

Response samples

200
401
500

Content type

application/json

{"id": "507f1f77bcf86cd799439011",
"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"action": "allow",
"active": true,
"filter": {"hostname": ".*"
},
"priority": 1,
"source_ip": ".*",
"username": ".*"
}

Delete firewall rule

Delete a firewall rule.

Authorizations:

jwt

path Parameters

id

required

integer

Firewall rule's ID

Responses

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Add a tag to firewall rule

Authorizations:

jwt

path Parameters

id

required

string

Firewall rule's ID

Request Body schema: application/json

tag

required

string

Responses

Request samples

Payload

Content type

application/json

{"tag": "tag1"
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Remove a tag from firewall rule

Authorizations:

jwt

path Parameters

id

required

string

Firewall rule's ID

Request Body schema: application/json

tag

required

string

Responses

Request samples

Payload

Content type

application/json

{"tag": "tag1"
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Update tags in firewall rule

Authorizations:

jwt

path Parameters

id

required

string

Firewall rule's ID

Request Body schema: application/json

tags

required

Array of strings [ 1 .. 3 ] items

Responses

Request samples

Payload

Content type

application/json

{"tags": ["tag1",
"tag2",
"tag3"
]
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

announcements

Routes related to announcements resource

List announcements

List the announcements posted by ShellHub Cloud.

query Parameters

page	integer >= 1 Default: 1 Page number
per_page	integer [ 1 .. 100 ] Default: 10 Items per page
order_by	string Default: "desc" Enum: "asc" "desc" Example: order_by=asc Announcements' list order.

Responses

Response samples

200
500

Content type

application/json

[[{"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"
}
]
]

Get a announcement

Get a announcement.

path Parameters

uuid

required

string <uuid> (announcementUUID)

Example: 3dd0d1f8-8246-4519-b11a-a3dd33717f65

Announcement UUID.

Responses

Response samples

200
500

Content type

application/json

{"uuid": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"title": "string",
"content": "# Pendent ignarus\n\n## Inmittitur insula praecipiunt viro odiumque campis securus\n\nLorem markdownum quamvis Sipylus sanguine, *feramus deam* virtus nosse clamor\nsuperbia me vivit, lumen. Quid clamore: hi quem. Dea dedit coram, patriam crura\ndum necis de exanimem. Sub habendus, iubet gentis transformat iter; latet nemus\nes somnum praecepta saxa.\n\n    if (firewire(daw, word_southbridge)) {\n        art.api.displayHdtvRom(access * minimize_hover_exif,\n                animated_redundancy);\n    }\n    var drop = real;\n    var pci_mtu_binary = dropPartitionGigabit.open_sound_computer(metal -\n            repositoryUrl, directx_memory + grep_remote_ram,\n            zifFlopsDevice.bar.wimax(ribbonVpiSip, commerce, 65));\n    if (web) {\n        sectorThird = ipComputerCharacter(5, pppoe_raw_brouter(\n                vpnAnimatedSubnet));\n    } else {\n        volumeRate += zebibyte_wired * responsiveIo;\n        vram_undo += function_ppc_ole.leaf_graphic(broadbandCleanUdp);\n        pci.compression_source_adsl += frozenServerNvram(tape_io, transistor);\n    }\n\n## Operosa si inque\n\nIacuere ut frontem *primum* nympha nec, ex mihi; nec in! Poma dolori incomitata\nNec. Sua senex quod, flavescunt libro nostris cum.\n\n1. Subiere bracchia ergo tumulavit namque inania\n2. Ictu bellum\n3. Feratis matrumque inritata Ophionides fila agricolis quique\n\n## Quaeritis sitim\n\nVelatus quae prodest manet reparabile antraque Pallas viridique\n[ducentem](http://modo-sic.net/) arcus. Alta per, cum. **Est** vinctum animae\nanima monte Propoetides praevitiat aliter montibus sua colligit [vasta\nrabiemque](http://mox.com/pereunt) habet. Edere iste aut, peregrina feramus,\niusserat sibilat huius, et.\n\n- Corpora a sequor muneris in pietas abdidit\n- Terribili tantum\n- Ubi potitur aberat aut animi quaesita manat\n- Eas duros valerem convivia et videt mirator\n- Sonitum et ait digna persequitur Trachinia est\n- Ipse corpora et totis temptaretque neque\n\n## Iterum in tinnulaque frondes culpae spumantis\n\nSub Mavortia illa nudos obstupuere **quantum** secum mitia Apolline tumere, non\nadhuc audistis ferre. Accepto vocabant movit spe; vere medii adloquitur vano\npernocte, everterit harundine simul, sortis causa. Animam [duo\ncausa](http://augustumme.com/puppim) mihi solent in ego quaecumque tarda, et\nquas: aere quae Avernae Amphitryoniaden.\n\n> Ventos fixit culpam vocavit iubasque. Sic venit tam ferinas freto pallescere\n> vadit: tamen Editus nil te, habet tantum minatur species et enixa. Conplevit\n> tenens Ladon, fugit studioque ausae Cerberon non maiora, tollit adhuc ait in\n> quae Atlantiades altae pulcherrime. Anima signa membra cursus, grandior\n> morientis fidem.\n\nMaduere in lacrimis in ultima verbaque pelle. Cervus suas tauro eripitur traho\nscelerata Hippason et est posse exuit quem per possent valet Alcmena annis et,\nut. Utrumque nam nitor sua ultima ferox liquerunt stetimusque **Semeles ianua**.\nIlli poma implesset sive: inde sub contingere veneratur salientis pectore mirata\net Neptunum veniet turis exitium. Quem sensit iam reclusa plus resurgere nescio\nmiratur ibat flamma [tuentes Minervae\nfortibus](http://intervitae.org/caputex.aspx) canebat et.",
"date": "2019-08-24T14:15:22Z"
}

mfa

Routes related to MFA

Auth MFA

Authenticate a user who has MFA enabled. This endpoint should be called after the default authUser endpoint, which generates an X-MFA-Token indicating that the user has already authenticated with a password.

Request Body schema: application/json

token required	string The `X-MFA-Token` header returned by the authUser endpoint.
code required	string The current code from the MFA authenticator.

Responses

Request samples

Payload

Content type

application/json

{"token": "bf265bf8-0065-4f44-a3ac-55eb3134c6ec",
"code": "123456"
}

Response samples

200
401
500

Content type

application/json

{"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJleGFtcGxlIiwibmFtZSI6ImV4YW1wbGUiLCJpYXQiOjE1MTYyMzkwMjJ9.zqCt70KspnNnitZlv89hDbFZ5iGMMRUn0wFEmmlY-to",
"id": "507f1f77bcf86cd799439011",
"user": "example",
"name": "example",
"email": "example@example.com",
"recovery_email": "user@example.com",
"tenant": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"role": "administrator",
"mfa": false,
"max_namespaces": 3
}

Recover MFA

Recover account access by providing one of the user's recovery codes. It will be invalidated for future uses.

The recovery code will be cached for 10 minutes. During this period, the user can use the same recovery code to disable their MFA without needing to provide two separate codes. The X-Expires-At header specifies the epoch value marking the end of the cache period.

Request Body schema: application/json

identifier required	string The same as the login identifier; can be either the user's email or username.
recovery_code required	string One of the user's recovery codes.

Responses

Request samples

Payload

Content type

application/json

{"identifier": "john_doe",
"recovery_code": "6DIGYYGM3JM7GXC4"
}

Response samples

200
401
500

Content type

application/json

{"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJleGFtcGxlIiwibmFtZSI6ImV4YW1wbGUiLCJpYXQiOjE1MTYyMzkwMjJ9.zqCt70KspnNnitZlv89hDbFZ5iGMMRUn0wFEmmlY-to",
"id": "507f1f77bcf86cd799439011",
"user": "example",
"name": "example",
"email": "example@example.com",
"recovery_email": "user@example.com",
"tenant": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"role": "administrator",
"mfa": false,
"max_namespaces": 3
}

Request Reset MFA

Sends an email to both the user's main and recovery addresses. Each email contains a unique code, which remains valid for at most 1 day. The user must provide both codes to reset their MFA.

Request Body schema: application/json

identifier

required

string

The same as the login identifier; can be either the user's email or username.

Responses

Request samples

Payload

Content type

application/json

{"identifier": "john_doe"
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Generate MFA Credentials

Generate the credentials to enable a user's MFA. The user must save the recovery codes a secure manner.

Authorizations:

jwt

Responses

Response samples

200
401
500

Content type

application/json

{"link": "otpauth://totp/shellhub-enterprise:662ba312616a7bdb5a2b608d?issuer=shellhub-enterprise&secret=TWBIH44WRHW44B773HJSG3RNZXH4KWSD",
"secret": "TWBIH44WRHW44B773HJSG3RNZXH4KWSD",
"recovery_codes": [["MLNSPOB2L2ZRO2D5",
"35QBUON4JAA4V6KP",
"UYH34OY5RNDRRSUS",
"IBWGL3IN42LTS3PP",
"6DIGYYGM3JM7GXC4",
"6UIHAIN3CYUEFY5X"
]
]
}

Enable MFA

Enable MFA for a user. The secret and recovery codes must be created by the generateMFA endpoint. Users with MFA already enabled cannot override their MFA credentials; in these cases, a user must disable MFA before proceeding. The recovery e-mail must be a valid value in order to enable the MFA.

Authorizations:

jwt

Request Body schema: application/json

code required	string The code generated by the MFA app.
secret required	string The secret generated by generateMFA endpoint.
recovery_codes required	Array of strings A list of codes generated by generateMFA endpoint. These codes can be used when a user loses their MFA app.

Responses

Request samples

Payload

Content type

application/json

{"code": "123456",
"secret": "TWBIH44WRHW44B773HJSG3RNZXH4KWSD",
"recovery_codes": [["MLNSPOB2L2ZRO2D5",
"35QBUON4JAA4V6KP",
"UYH34OY5RNDRRSUS",
"IBWGL3IN42LTS3PP",
"6DIGYYGM3JM7GXC4",
"6UIHAIN3CYUEFY5X"
]
]
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Disable MFA

Disable MFA for a user. To disable MFA, the user must provide either a recovery code or the current MFA code. If a recovery code is used, it will be invalidated for future use.

The recovery code used to regain access to the account can be used within a 10-minute window on this endpoint.

Authorizations:

jwt

Request Body schema: application/json

code	string The code generated by the MFA app.
recovery_code	string User's recovery code.

Responses

Request samples

Payload

Content type

application/json

{"code": "123456",
"recovery_code": "6UIHAIN3CYUEFY5X"
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Reset MFA

Similar to the disableMFA operation, this endpoint uses the two codes sent by requestResetMFA instead of a TOTP or recovery code. The user ID must be the same as the one used for requestResetMFA.

path Parameters

user-id

string

Example: 664e02087116dc765ef876a0

ID of the user trying to reset MFA.

Request Body schema: application/json

main_email_code required	string The code sent to the main email address.
recovery_email_code required	string The code sent to the recovery email address.

Responses

Request samples

Payload

Content type

application/json

{"main_email_code": "JR36Q",
"recovery_email_code": "AB2D8"
}

Response samples

200
401
500

Content type

application/json

{"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJleGFtcGxlIiwibmFtZSI6ImV4YW1wbGUiLCJpYXQiOjE1MTYyMzkwMjJ9.zqCt70KspnNnitZlv89hDbFZ5iGMMRUn0wFEmmlY-to",
"id": "507f1f77bcf86cd799439011",
"user": "example",
"name": "example",
"email": "example@example.com",
"recovery_email": "user@example.com",
"tenant": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"role": "administrator",
"mfa": false,
"max_namespaces": 3
}

api-keys

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.

Creates an API key.

The created_by, tenant_id, and role (unless provided in the request body) values will be obtained from the JWT token.

Authorizations:

jwt

Request Body schema: application/json

name required	string [ 3 .. 20 ] characters The name of the API key. This serves as an "external ID" since the UUID will never be returned. It is unique per namespace.
expires_at required	integer Enum: -1 30 60 90 365 Number of days until expiration. Use -1 for no expiration.
role	string The role of the key. It serves as a "level" indicating which endpoints the key can access. It must be less or equal than the user's role. Leave it blank to use the user's role.
key	string <uuidv4> An optional and unique value to be used as the API key's internal identifier. This value is the "internal ID" and will NEVER be returned to the client. Leave it blank for a random one to be generated.

Responses

Request samples

Payload

Content type

application/json

{"name": "dev",
"expires_at": 30,
"role": "owner",
"key": "c629572a-b643-4301-90fe-4572b00d007e"
}

Response samples

200
401
500

Content type

application/json

{"id": "c629572a-b643-4301-90fe-4572b00d007e",
"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"created_by": "507f1f77bcf86cd799439011",
"role": "owner",
"name": "dev",
"expires_in": 1707958989,
"created_at": "2020-05-01T00:00:00.000Z",
"updated_at": "2020-05-01T00:00:00.000Z"
}

List API Keys

Authorizations:

jwtapi-key

query Parameters

page	integer >= 1 Default: 1 Page number
per_page	integer [ 1 .. 100 ] Default: 10 Items per page
order_by	string Default: "desc" Enum: "asc" "desc" The list order.
sort_by	string Default: "expires_in" Example: sort_by=name The property to sort of.

Responses

Response samples

200
401
500

Content type

application/json

[{"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"created_by": "507f1f77bcf86cd799439011",
"role": "owner",
"name": "dev",
"expires_in": 1707958989,
"created_at": "2020-05-01T00:00:00.000Z",
"updated_at": "2020-05-01T00:00:00.000Z"
}
]

Update an API key

Authorizations:

jwt

path Parameters

key	string Example: dev The API key name.

Request Body schema: application/json

name	string [ 3 .. 20 ] characters The name of the API key. This serves as an "external ID" since the UUID will never be returned. It is unique per namespace.
role	string The role of the key. It serves as a "level" indicating which endpoints the key can access. It must be less or equal than the user's role.

Responses

Request samples

Payload

Content type

application/json

{"name": "dev",
"role": "owner"
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Delete an API key

Authorizations:

jwt

path Parameters

key	string Example: dev The API key name.

Responses

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

billing

Create customer

creates a new customer defining, optionaly, the default payment method.

Authorizations:

jwt

Responses

Response samples

Content type

application/json

{"message": "string",
"code": "string"
}

Get Customer

Get the customer.

Authorizations:

jwt

Responses

Response samples

Content type

application/json

{"id": "cus_H9J5n2eZvKYlo2C7X1QX2Qg",
"name": "user",
"email": "user@shellhub.io",
"payment_methods": [{"id": "pm_1H9J5n2eZvKYlo2C7X1QX2Qg",
"number": "4242424242424242",
"brand": "visa",
"exp_month": 10,
"exp_year": 2030,
"cvc": "123",
"default": true
}
]
}

Create subscription

Create a subscription.

Authorizations:

jwt

Responses

Response samples

Content type

application/json

{"message": "string",
"code": "string"
}

Get subscription

Get the subscription.

Authorizations:

jwt

Responses

Response samples

Content type

application/json

{"id": "sub_H9J5n2eZvKYlo2C7X1QX2Qg",
"active": true,
"status": "active",
"end_at": 31536000,
"invoices": [{"id": "in_H9J5n2eZvKYlo2C7X1QX2Qg",
"status": "open",
"currency": "usd",
"amount": 0
}
]
}

Attach payment method

Attachs a payment method to a customer.

Authorizations:

jwt

Request Body schema: application/json

id

required

string

Payment method's ID.

Responses

Request samples

Payload

Content type

application/json

{"id": "pm_H9J5n2eZvKYlo2C7X1QX2Qg"
}

Response samples

Content type

application/json

{"message": "string",
"code": "string"
}

Detach payment method

Detachs a payment method from a customer.

Authorizations:

jwt

Request Body schema: application/json

id

required

string

Payment method's ID.

Responses

Request samples

Payload

Content type

application/json

{"id": "pm_H9J5n2eZvKYlo2C7X1QX2Qg"
}

Response samples

Content type

application/json

{"message": "string",
"code": "string"
}

Set default payment method

Set default payment method to the customer.

Authorizations:

jwt

Request Body schema: application/json

id

required

string

Payment method's ID.

Responses

Request samples

Payload

Content type

application/json

{"id": "pm_H9J5n2eZvKYlo2C7X1QX2Qg"
}

Response samples

Content type

application/json

{"message": "string",
"code": "string"
}

Choice devices

Choice devices when device's limit is rechead.

Authorizations:

jwt

Request Body schema: application/json

choices

required

Array of strings[ items [ 0 .. 3 ] items ]

Device's list.

Responses

Request samples

Payload

Content type

application/json

{"choices": ["string"
]
}

Response samples

500

Content type

application/json

{"message": "Internal Server Error"
}

Get devices most used

Get the most used devices.

Authorizations:

jwt

Responses

Response samples

200
500

Content type

application/json

[{"uid": "13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a",
"name": "example",
"identity": {"mac": "00:00:00:00:00:00"
},
"info": {"id": "example",
"pretty_name": "linux",
"version": "latest",
"arch": "x86_64",
"platform": "docker"
},
"public_key": "-----BEGIN RSA PUBLIC KEY-----MIIBCgKCAQEA0vH2Bob3mn+uWVaHlOoZD8ai01W6VnRTnXlnHVF7Ny1Vb7pl1Hc4D8bsBhb1vt7aZOYHbCyDR2r5lsrWXCELE8pY8vzfFDA+jNrLbBCJ66E1BcmTqfXCJcLospWD2lIAwU2O7IPxwZujuVkHrF8nYuEFsKeG60QTWNS++RTqydqe2KmFMEdWCQmYPm/ykN871fSR9+PzoRJMYWidY6Szn+X2ardGmS/Ldhl/PEu9h7xjcQXANWz6yV/RVReGVkLcK6TxlfuxgdpbsWAx+cS52P7xWrshNefHqjpdlm3KNbo6vqfTpU8Ld/FFISXXaa1Md5GyAHF+jzuRzQ5z5aKBGwIDAQAB-----END RSA PUBLIC KEY-----",
"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"last_seen": "2020-01-01T00:00:00Z",
"online": true,
"namespace": "examplespace",
"status": "accepted",
"status_update_at": "2020-05-01T00:00:00.000Z",
"created_at": "2020-01-01T00:00:00Z",
"remote_addr": "127.0.0.1",
"position": {"latitude": -31.7566628,
"longitude": -52.322474
},
"tags": ["tag1",
"tag2",
"tag3"
],
"public_url": false,
"acceptable": false
}
]

Report

Report an action.

Authorizations:

jwt

query Parameters

action

required

string

Enum: "device_accept" "namespace_delete"

Responses

Response samples

Content type

application/json

"string"

Evaluate

evaluate the namespace capabilities.

Authorizations:

jwt

Responses

Response samples

Content type

application/json

{"can_accept": false,
"can_connect": true
}

namespaces

Connector's create

Create a new connector.

Authorizations:

jwt

Request Body schema: application/json
required

enable	boolean Connector's connection is enabled.
address	string <hostname> Address to the Container Engine.
port	integer [ 0 .. 65535 ] Port to the Container Engine.
secure	boolean onnector's connection is using HTTPS for authentication.
	object (connectorTLS)

Responses

Request samples

Payload

Content type

application/json

{"enable": true,
"address": "127.0.0.1",
"port": 2375,
"secure": false,
"tls": null
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Connector's list

List connectors.

Authorizations:

jwt

query Parameters

enable	boolean Enable status.
page	integer >= 1 Default: 1 Page number
per_page	integer [ 1 .. 100 ] Default: 10 Items per page

Responses

Response samples

200
401
500

Content type

application/json

[{"uid": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"enable": true,
"address": "127.0.0.1",
"port": 2375,
"secure": false,
"status": {"State": "connected",
"Message": ""
},
"tls": null
}
]

Connector's get

Gets a connector.

Authorizations:

jwt

path Parameters

uid

required

string

Connector UID

Responses

Response samples

200
401
500

Content type

application/json

{"uid": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"enable": true,
"address": "127.0.0.1",
"port": 2375,
"secure": false,
"status": {"State": "connected",
"Message": ""
},
"tls": null
}

Connector's setting update

Updates a connector settings.

Authorizations:

jwt

path Parameters

uid

required

string

Connector UID

Request Body schema: application/json
required

enable	boolean Connector's connection is enabled.
address	string <hostname> Address to the Container Engine.
port	integer [ 0 .. 65535 ] Port to the Container Engine.
secure	boolean onnector's connection is using HTTPS for authentication.
	object (connectorTLS)

Responses

Request samples

Payload

Content type

application/json

{"enable": true,
"address": "127.0.0.1",
"port": 2375,
"secure": false,
"tls": null
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Connector's delete

Deletes a connector.

Authorizations:

jwt

path Parameters

uid

required

string

Connector UID

Responses

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Connector's get Docker info

Gets the connector's connection docker info.

Authorizations:

jwt

path Parameters

uid

required

string

Connector UID

Responses

Response samples

200
401
500

Content type

application/json

{"ID": "string",
"Containers": 0,
"ContainersRunning": 0,
"ContainersPaused": 0,
"ContainersStopped": 0,
"Images": 0,
"Driver": "string",
"DriverStatus": [["string"
]
],
"Plugins": {"Volume": ["string"
],
"Network": ["string"
],
"Authorization": ["string"
],
"Log": ["string"
]
},
"MemoryLimit": true,
"SwapLimit": true,
"CpuCfsPeriod": true,
"CpuCfsQuota": true,
"CPUShares": true,
"CPUSet": true,
"PidsLimit": true,
"IPv4Forwarding": true,
"BridgeNfIptables": true,
"BridgeNfIp6tables": true,
"Debug": true,
"NFd": 0,
"OomKillDisable": true,
"NGoroutines": 0,
"SystemTime": "2019-08-24T14:15:22Z",
"LoggingDriver": "string",
"CgroupDriver": "string",
"CgroupVersion": "string",
"NEventsListener": 0,
"KernelVersion": "string",
"OperatingSystem": "string",
"OSVersion": "string",
"OSType": "string",
"Architecture": "string",
"IndexServerAddress": "string",
"RegistryConfig": {"AllowNondistributableArtifactsCIDRs": ["string"
],
"AllowNondistributableArtifactsHostnames": ["string"
],
"InsecureRegistryCIDRs": ["string"
],
"IndexConfigs": {"docker.io": {"Name": "string",
"Mirrors": ["string"
],
"Secure": true,
"Official": true
}
},
"Mirrors": ["string"
]
},
"NCPU": 0,
"MemTotal": 0,
"GenericResources": ["string"
],
"DockerRootDir": "string",
"HttpProxy": "string",
"HttpsProxy": "string",
"NoProxy": "string",
"Name": "string",
"Labels": ["string"
],
"ExperimentalBuild": true,
"ServerVersion": "string",
"Runtimes": {"io.containerd.runc.v2": {"path": "string",
"status": {"property1": "string",
"property2": "string"
}
},
"runc": {"path": "string",
"status": {"property1": "string",
"property2": "string"
}
}
},
"DefaultRuntime": "string",
"Swarm": {"NodeID": "string",
"NodeAddr": "string",
"LocalNodeState": "string",
"ControlAvailable": true,
"Error": "string",
"RemoteManagers": ["string"
]
},
"LiveRestoreEnabled": true,
"Isolation": "string",
"InitBinary": "string",
"ContainerdCommit": {"ID": "string",
"Expected": "string"
},
"RuncCommit": {"ID": "string",
"Expected": "string"
},
"InitCommit": {"ID": "string",
"Expected": "string"
},
"SecurityOptions": ["string"
],
"CDISpecDirs": ["string"
],
"Warnings": ["string"
]
}

Accept a membership invite

This route is intended to be accessed directly through the link sent in the invitation email. The user must be logged into the account that was invited.

Authorizations:

jwt

path Parameters

tenant

required

string <uuid> (namespaceTenantID)

Example: 3dd0d1f8-8246-4519-b11a-a3dd33717f65

Namespace's tenant ID

Request Body schema: application/json

sig

required

string

The unique key included in the email link.

Responses

Request samples

Payload

Content type

application/json

{"sig": "b25e93bc-22ac-4f02-901a-52af9f358a5d"
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Lookup User's Status

Clients may need to check a user's status before deciding whether to redirect to the accept-invite workflow or to the signup process. It is intended for use exclusively by clients in the invite-member pipeline.

path Parameters

tenant required	string The tenant ID of the namespace.
id required	string The user's ID.

query Parameters

sig

required

string

The signature included in the email. This is used instead of the user's token to authenticate the request.

Responses

Response samples

200
500

Content type

application/json

{"status": "invited"
}

Get a new namespace's token

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.

Authorizations:

jwt

path Parameters

tenant

required

string <uuid> (namespaceTenantID)

Example: 3dd0d1f8-8246-4519-b11a-a3dd33717f65

Namespace's tenant ID

Responses

Response samples

200
401
500

Content type

application/json

{"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJleGFtcGxlIiwibmFtZSI6ImV4YW1wbGUiLCJpYXQiOjE1MTYyMzkwMjJ9.zqCt70KspnNnitZlv89hDbFZ5iGMMRUn0wFEmmlY-to",
"id": "507f1f77bcf86cd799439011",
"user": "example",
"name": "example",
"email": "example@example.com",
"recovery_email": "user@example.com",
"tenant": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"role": "administrator",
"mfa": false,
"max_namespaces": 3
}

Get namespaces list

Returns a list of namespaces.

Authorizations:

jwt

query Parameters

filter	string^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==\|[... Example: filter=W3sidHlwZSI6InByb3BlcnR5IiwicGFyYW1zIjp7Im5hbWUiOiJuYW1lIiwib3BlcmF0b3IiOiJjb250YWlucyIsInZhbHVlIjoiZXhhbXBsZXNwYWNlIn19XQ== 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 `[ { "type":"property", "params":{ "name":"name", "operator":"contains", "value":"examplespace" } } ]` So, the output encoded string will result on: `W3sidHlwZSI6InByb3BlcnR5IiwicGFyYW1zIjp7Im5hbWUiOiJuYW1lIiwib3BlcmF0b3IiOiJjb250YWlucyIsInZhbHVlIjoiZXhhbXBsZXNwYWNlIn19XQ==`
page	integer >= 1 Default: 1 Page number
per_page	integer [ 1 .. 100 ] Default: 10 Items per page

Responses

Response samples

200
401
500

Content type

application/json

[{"name": "examplespace",
"owner": "507f1f77bcf86cd799439011",
"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"members": [{"id": "507f1f77bcf86cd799439011",
"added_at": "2024-09-03T23:17:50.51Z",
"expires_at": "0001-01-01T00:00:00Z",
"role": "administrator",
"status": "accepted",
"email": "john.doe@test.com"
}
],
"settings": {"session_record": true,
"connection_announcement": "my awesome connection announcement"
},
"max_devices": 3,
"device_count": 0,
"created_at": "2020-05-01T00:00:00.000Z",
"billing": null
}
]

Create namespace

Create a namespace.

Authorizations:

jwt

Request Body schema: application/json

name

required

string (namespaceName)

Namespace's name

Responses

Request samples

Payload

Content type

application/json

{"name": "examplespace"
}

Response samples

200
401
500

Content type

application/json

{"name": "examplespace",
"owner": "507f1f77bcf86cd799439011",
"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"members": [{"id": "507f1f77bcf86cd799439011",
"added_at": "2024-09-03T23:17:50.51Z",
"expires_at": "0001-01-01T00:00:00Z",
"role": "administrator",
"status": "accepted",
"email": "john.doe@test.com"
}
],
"settings": {"session_record": true,
"connection_announcement": "my awesome connection announcement"
},
"max_devices": 3,
"device_count": 0,
"created_at": "2020-05-01T00:00:00.000Z",
"billing": null
}

Get a namespace

Get a namespace.

Authorizations:

jwt

path Parameters

tenant

required

string <uuid> (namespaceTenantID)

Example: 3dd0d1f8-8246-4519-b11a-a3dd33717f65

Namespace's tenant ID

Responses

Response samples

200
401
500

Content type

application/json

{"name": "examplespace",
"owner": "507f1f77bcf86cd799439011",
"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"members": [{"id": "507f1f77bcf86cd799439011",
"added_at": "2024-09-03T23:17:50.51Z",
"expires_at": "0001-01-01T00:00:00Z",
"role": "administrator",
"status": "accepted",
"email": "john.doe@test.com"
}
],
"settings": {"session_record": true,
"connection_announcement": "my awesome connection announcement"
},
"max_devices": 3,
"device_count": 0,
"created_at": "2020-05-01T00:00:00.000Z",
"billing": null
}

Edit namespace

Edit a namespace.

Authorizations:

jwt

path Parameters

tenant

required

string <uuid> (namespaceTenantID)

Example: 3dd0d1f8-8246-4519-b11a-a3dd33717f65

Namespace's tenant ID

Request Body schema: application/json

name	string (namespaceName) Namespace's name
	object (namespaceSettings) Namespace's settings.

Responses

Request samples

Payload

Content type

application/json

{"name": "examplespace",
"settings": {"session_record": true,
"connection_announcement": "my awesome connection announcement"
}
}

Response samples

200
401
500

Content type

application/json

{"name": "examplespace",
"owner": "507f1f77bcf86cd799439011",
"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"members": [{"id": "507f1f77bcf86cd799439011",
"added_at": "2024-09-03T23:17:50.51Z",
"expires_at": "0001-01-01T00:00:00Z",
"role": "administrator",
"status": "accepted",
"email": "john.doe@test.com"
}
],
"settings": {"session_record": true,
"connection_announcement": "my awesome connection announcement"
},
"max_devices": 3,
"device_count": 0,
"created_at": "2020-05-01T00:00:00.000Z",
"billing": null
}

Delete namespace

Delete a namespace.

Authorizations:

jwt

path Parameters

tenant

required

string <uuid> (namespaceTenantID)

Example: 3dd0d1f8-8246-4519-b11a-a3dd33717f65

Namespace's tenant ID

Responses

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Leave Namespace

Allows the authenticated user to leave the specified namespace. Owners cannot leave a namespace and must delete it instead.

Authorizations:

jwt

path Parameters

tenant

required

string <uuid> (namespaceTenantID)

Example: 3dd0d1f8-8246-4519-b11a-a3dd33717f65

Namespace's tenant ID

Responses

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Invite member

Invites a member to a namespace.

In enterprise and community instances, the member will automatically accept the invite and will have an accepted status.

In cloud instances, the member will have a pending status until they accept the invite via an email sent to them. The invite is valid for 7 days. If the member was previously invited and the invite is no longer valid, the same route will resend the invite.

Authorizations:

jwt

path Parameters

tenant

required

string <uuid> (namespaceTenantID)

Example: 3dd0d1f8-8246-4519-b11a-a3dd33717f65

Namespace's tenant ID

Request Body schema: application/json

email required	string The email of the member.
role required	string (namespaceMemberRole) Enum: "administrator" "operator" "observer" "owner" Namespace's member role

Responses

Request samples

Payload

Content type

application/json

{"email": "john.doe@test.com",
"role": "administrator"
}

Response samples

200
401
500

Content type

application/json

{"name": "examplespace",
"owner": "507f1f77bcf86cd799439011",
"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"members": [{"id": "507f1f77bcf86cd799439011",
"added_at": "2024-09-03T23:17:50.51Z",
"expires_at": "0001-01-01T00:00:00Z",
"role": "administrator",
"status": "accepted",
"email": "john.doe@test.com"
}
],
"settings": {"session_record": true,
"connection_announcement": "my awesome connection announcement"
},
"max_devices": 3,
"device_count": 0,
"created_at": "2020-05-01T00:00:00.000Z",
"billing": null
}

Remove a member from a namespace

Remove a member from a namespace.

Authorizations:

jwt

path Parameters

tenant required	string <uuid> (namespaceTenantID) Example: 3dd0d1f8-8246-4519-b11a-a3dd33717f65 Namespace's tenant ID
uid required	string Member's ID

Responses

Response samples

200
401
500

Content type

application/json

{"name": "examplespace",
"owner": "507f1f77bcf86cd799439011",
"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"members": [{"id": "507f1f77bcf86cd799439011",
"added_at": "2024-09-03T23:17:50.51Z",
"expires_at": "0001-01-01T00:00:00Z",
"role": "administrator",
"status": "accepted",
"email": "john.doe@test.com"
}
],
"settings": {"session_record": true,
"connection_announcement": "my awesome connection announcement"
},
"max_devices": 3,
"device_count": 0,
"created_at": "2020-05-01T00:00:00.000Z",
"billing": null
}

Update a member from a namespace

Update a member role from a namespace.

Authorizations:

jwt

path Parameters

tenant required	string <uuid> (namespaceTenantID) Example: 3dd0d1f8-8246-4519-b11a-a3dd33717f65 Namespace's tenant ID
uid required	string Member's ID

Request Body schema: application/json

role	string (namespaceMemberRole) Enum: "administrator" "operator" "observer" "owner" Namespace's member role

Responses

Request samples

Payload

Content type

application/json

{"role": "administrator"
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Creates an API key.

The created_by, tenant_id, and role (unless provided in the request body) values will be obtained from the JWT token.

Authorizations:

jwt

Request Body schema: application/json

name required	string [ 3 .. 20 ] characters The name of the API key. This serves as an "external ID" since the UUID will never be returned. It is unique per namespace.
expires_at required	integer Enum: -1 30 60 90 365 Number of days until expiration. Use -1 for no expiration.
role	string The role of the key. It serves as a "level" indicating which endpoints the key can access. It must be less or equal than the user's role. Leave it blank to use the user's role.
key	string <uuidv4> An optional and unique value to be used as the API key's internal identifier. This value is the "internal ID" and will NEVER be returned to the client. Leave it blank for a random one to be generated.

Responses

Request samples

Payload

Content type

application/json

{"name": "dev",
"expires_at": 30,
"role": "owner",
"key": "c629572a-b643-4301-90fe-4572b00d007e"
}

Response samples

200
401
500

Content type

application/json

{"id": "c629572a-b643-4301-90fe-4572b00d007e",
"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"created_by": "507f1f77bcf86cd799439011",
"role": "owner",
"name": "dev",
"expires_in": 1707958989,
"created_at": "2020-05-01T00:00:00.000Z",
"updated_at": "2020-05-01T00:00:00.000Z"
}

List API Keys

Authorizations:

jwtapi-key

query Parameters

page	integer >= 1 Default: 1 Page number
per_page	integer [ 1 .. 100 ] Default: 10 Items per page
order_by	string Default: "desc" Enum: "asc" "desc" The list order.
sort_by	string Default: "expires_in" Example: sort_by=name The property to sort of.

Responses

Response samples

200
401
500

Content type

application/json

[{"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"created_by": "507f1f77bcf86cd799439011",
"role": "owner",
"name": "dev",
"expires_in": 1707958989,
"created_at": "2020-05-01T00:00:00.000Z",
"updated_at": "2020-05-01T00:00:00.000Z"
}
]

Update an API key

Authorizations:

jwt

path Parameters

key	string Example: dev The API key name.

Request Body schema: application/json

name	string [ 3 .. 20 ] characters The name of the API key. This serves as an "external ID" since the UUID will never be returned. It is unique per namespace.
role	string The role of the key. It serves as a "level" indicating which endpoints the key can access. It must be less or equal than the user's role.

Responses

Request samples

Payload

Content type

application/json

{"name": "dev",
"role": "owner"
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Delete an API key

Authorizations:

jwt

path Parameters

key	string Example: dev The API key name.

Responses

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

members

Accept a membership invite

This route is intended to be accessed directly through the link sent in the invitation email. The user must be logged into the account that was invited.

Authorizations:

jwt

path Parameters

tenant

required

string <uuid> (namespaceTenantID)

Example: 3dd0d1f8-8246-4519-b11a-a3dd33717f65

Namespace's tenant ID

Request Body schema: application/json

sig

required

string

The unique key included in the email link.

Responses

Request samples

Payload

Content type

application/json

{"sig": "b25e93bc-22ac-4f02-901a-52af9f358a5d"
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Lookup User's Status

Clients may need to check a user's status before deciding whether to redirect to the accept-invite workflow or to the signup process. It is intended for use exclusively by clients in the invite-member pipeline.

path Parameters

tenant required	string The tenant ID of the namespace.
id required	string The user's ID.

query Parameters

sig

required

string

The signature included in the email. This is used instead of the user's token to authenticate the request.

Responses

Response samples

200
500

Content type

application/json

{"status": "invited"
}

Leave Namespace

Allows the authenticated user to leave the specified namespace. Owners cannot leave a namespace and must delete it instead.

Authorizations:

jwt

path Parameters

tenant

required

string <uuid> (namespaceTenantID)

Example: 3dd0d1f8-8246-4519-b11a-a3dd33717f65

Namespace's tenant ID

Responses

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Invite member

Invites a member to a namespace.

In enterprise and community instances, the member will automatically accept the invite and will have an accepted status.

In cloud instances, the member will have a pending status until they accept the invite via an email sent to them. The invite is valid for 7 days. If the member was previously invited and the invite is no longer valid, the same route will resend the invite.

Authorizations:

jwt

path Parameters

tenant

required

string <uuid> (namespaceTenantID)

Example: 3dd0d1f8-8246-4519-b11a-a3dd33717f65

Namespace's tenant ID

Request Body schema: application/json

email required	string The email of the member.
role required	string (namespaceMemberRole) Enum: "administrator" "operator" "observer" "owner" Namespace's member role

Responses

Request samples

Payload

Content type

application/json

{"email": "john.doe@test.com",
"role": "administrator"
}

Response samples

200
401
500

Content type

application/json

{"name": "examplespace",
"owner": "507f1f77bcf86cd799439011",
"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"members": [{"id": "507f1f77bcf86cd799439011",
"added_at": "2024-09-03T23:17:50.51Z",
"expires_at": "0001-01-01T00:00:00Z",
"role": "administrator",
"status": "accepted",
"email": "john.doe@test.com"
}
],
"settings": {"session_record": true,
"connection_announcement": "my awesome connection announcement"
},
"max_devices": 3,
"device_count": 0,
"created_at": "2020-05-01T00:00:00.000Z",
"billing": null
}

system

Get info

Get information about ShellHub instance like version, SSH and API addresses.

query Parameters

agent_version

string

Agent's version.

Responses

Response samples

200
500

Content type

application/json

{"version": "latest",
"endpoints": {"ssh": "localhost:2222",
"api": "localhost"
},
"setup": true
}

User setup

Register an user and create namespace with the same name as username

query Parameters

sign

required

string

Signature used to validate request origin generated by running ./bin/setup script

Request Body schema: application/json

name required	string (userName) [ 3 .. 20 ] characters User's name.
email required	string <email> (userEmail) User's E-mail.
username required	string (userUsername) [ 3 .. 30 ] characters ^[a-zA-Z0-9-_.@]{3,30}$ User's username.
password required	string (userPassword) [ 5 .. 30 ] characters User's password.

Responses

Request samples

Payload

Content type

application/json

{"name": "example",
"email": "example@example.com",
"username": "example",
"password": "example"
}

Response samples

500

Content type

application/json

{"message": "Internal Server Error"
}

external

Login

Authenticate a user, returning the session's JWT token and user data.

Authentication may result in an account lockout after N consecutive incorrect login attempts. The lockout applies specifically to a particular source and user combination. Check for the presence of the X-Account-Lockout header to determine the account lockout status. When it's 0, there are no active lockouts.

Users with MFA enabled cannot authenticate via this route. In such cases, the API will respond with a status 401 and an X-MFA-Token header with a UUID. Authentication must be med to /api/mfa/auth with this token in these instances.

Request Body schema: application/json

username required	string (userUsername) [ 3 .. 30 ] characters ^[a-zA-Z0-9-_.@]{3,30}$ User's username.
password required	string (userPassword) [ 5 .. 30 ] characters User's password.

Responses

Request samples

Payload

Content type

application/json

{"username": "example",
"password": "example"
}

Response samples

200
500

Content type

application/json

{"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJleGFtcGxlIiwibmFtZSI6ImV4YW1wbGUiLCJpYXQiOjE1MTYyMzkwMjJ9.zqCt70KspnNnitZlv89hDbFZ5iGMMRUn0wFEmmlY-to",
"id": "507f1f77bcf86cd799439011",
"user": "example",
"name": "example",
"email": "example@example.com",
"recovery_email": "user@example.com",
"tenant": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"role": "administrator",
"mfa": false,
"max_namespaces": 3
}

Auth a user

Authenticate a user, returning the session's JWT token and data about the user.

Request Body schema: application/json

username required	string (userUsername) [ 3 .. 30 ] characters ^[a-zA-Z0-9-_.@]{3,30}$ User's username.
password required	string (userPassword) [ 5 .. 30 ] characters User's password.

Responses

Request samples

Payload

Content type

application/json

{"username": "example",
"password": "example"
}

Response samples

200
401
500

Content type

application/json

{"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJleGFtcGxlIiwibmFtZSI6ImV4YW1wbGUiLCJpYXQiOjE1MTYyMzkwMjJ9.zqCt70KspnNnitZlv89hDbFZ5iGMMRUn0wFEmmlY-to",
"id": "507f1f77bcf86cd799439011",
"user": "example",
"name": "example",
"email": "example@example.com",
"recovery_email": "user@example.com",
"tenant": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"role": "administrator",
"mfa": false,
"max_namespaces": 3
}

internal

Auth device

Authenticate a ShellHub agent into the ShellHub server.

Every 30 seconds, this route is hit by ShellHub agent to inform device availability.

Authorizations:

jwt

header Parameters

X-Real-IP

string^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,...

Example: 127.0.0.1

Device's IP address.

X-Real-IP header is used to set a geolocation position to device when geoip feature is enable.

Request Body schema: application/json

required	object (deviceInfo) Device's info
sessions	Array of strings
hostname required	string([a-zA-Z0-9]\|[a-zA-Z0-9][a-zA-Z0-9\-]*[a-zA-Z...
	object (deviceIdentity) Device's identity
public_key required	string Device's public key.
tenant_id required	string <uuid> (namespaceTenantID) Namespace's tenant ID

Responses

Request samples

Payload

Content type

application/json

{"info": {"id": "example",
"pretty_name": "linux",
"version": "latest",
"arch": "x86_64",
"platform": "docker"
},
"sessions": ["string"
],
"hostname": "string",
"identity": {"mac": "00:00:00:00:00:00"
},
"public_key": "string",
"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65"
}

Response samples

200
401
500

Content type

application/json

{"uid": "13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.iUCROHt6JHANdtzT6aOuUgOqVFRalOW20SbzRsn5SkI\n",
"name": "example",
"namespace": "examplespace"
}

Auth device

Authenticate a ShellHub agent into the ShellHub server.

Every 30 seconds, this route is hit by ShellHub agent to inform device availability.

Authorizations:

jwt

header Parameters

X-Real-IP

string^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,...

Example: 127.0.0.1

Device's IP address.

X-Real-IP header is used to set a geolocation position to device when geoip feature is enable.

Request Body schema: application/json

required	object (deviceInfo) Device's info
sessions	Array of strings
hostname required	string([a-zA-Z0-9]\|[a-zA-Z0-9][a-zA-Z0-9\-]*[a-zA-Z...
	object (deviceIdentity) Device's identity
public_key required	string Device's public key.
tenant_id required	string <uuid> (namespaceTenantID) Namespace's tenant ID

Responses

Request samples

Payload

Content type

application/json

{"info": {"id": "example",
"pretty_name": "linux",
"version": "latest",
"arch": "x86_64",
"platform": "docker"
},
"sessions": ["string"
],
"hostname": "string",
"identity": {"mac": "00:00:00:00:00:00"
},
"public_key": "string",
"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65"
}

Response samples

200
401
500

Content type

application/json

{"uid": "13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.iUCROHt6JHANdtzT6aOuUgOqVFRalOW20SbzRsn5SkI\n",
"name": "example",
"namespace": "examplespace"
}

Auth SSH public key

Authenticate a SSH public key to ShellHub server.

Authorizations:

jwt

Request Body schema: application/json

fingerprint required	string (publickKeyFingerprint) ^([0-9a-f]{2}:){15}[0-9a-f]{2}$ Public key's fingerprint.
data required	string Public key's data.

Responses

Request samples

Payload

Content type

application/json

{"fingerprint": "48:6e:fc:94:01:01:74:57:eb:57:49:91:15:e4:9c:7a",
"data": "string"
}

Response samples

200
401
500

Content type

application/json

{"signature": "string"
}

Update device status to offline

Update device's status to offiline.

Authorizations:

jwt

path Parameters

uid

required

string (deviceUID) ^[0-9a-f]{64}$

Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a

Device's UID

Responses

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

devices

Auth device

Authenticate a ShellHub agent into the ShellHub server.

Every 30 seconds, this route is hit by ShellHub agent to inform device availability.

Authorizations:

jwt

header Parameters

X-Real-IP

string^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,...

Example: 127.0.0.1

Device's IP address.

X-Real-IP header is used to set a geolocation position to device when geoip feature is enable.

Request Body schema: application/json

required	object (deviceInfo) Device's info
sessions	Array of strings
hostname required	string([a-zA-Z0-9]\|[a-zA-Z0-9][a-zA-Z0-9\-]*[a-zA-Z...
	object (deviceIdentity) Device's identity
public_key required	string Device's public key.
tenant_id required	string <uuid> (namespaceTenantID) Namespace's tenant ID

Responses

Request samples

Payload

Content type

application/json

{"info": {"id": "example",
"pretty_name": "linux",
"version": "latest",
"arch": "x86_64",
"platform": "docker"
},
"sessions": ["string"
],
"hostname": "string",
"identity": {"mac": "00:00:00:00:00:00"
},
"public_key": "string",
"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65"
}

Response samples

200
401
500

Content type

application/json

{"uid": "13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.iUCROHt6JHANdtzT6aOuUgOqVFRalOW20SbzRsn5SkI\n",
"name": "example",
"namespace": "examplespace"
}

Auth device

Authenticate a ShellHub agent into the ShellHub server.

Every 30 seconds, this route is hit by ShellHub agent to inform device availability.

Authorizations:

jwt

header Parameters

X-Real-IP

string^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,...

Example: 127.0.0.1

Device's IP address.

X-Real-IP header is used to set a geolocation position to device when geoip feature is enable.

Request Body schema: application/json

required	object (deviceInfo) Device's info
sessions	Array of strings
hostname required	string([a-zA-Z0-9]\|[a-zA-Z0-9][a-zA-Z0-9\-]*[a-zA-Z...
	object (deviceIdentity) Device's identity
public_key required	string Device's public key.
tenant_id required	string <uuid> (namespaceTenantID) Namespace's tenant ID

Responses

Request samples

Payload

Content type

application/json

{"info": {"id": "example",
"pretty_name": "linux",
"version": "latest",
"arch": "x86_64",
"platform": "docker"
},
"sessions": ["string"
],
"hostname": "string",
"identity": {"mac": "00:00:00:00:00:00"
},
"public_key": "string",
"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65"
}

Response samples

200
401
500

Content type

application/json

{"uid": "13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.iUCROHt6JHANdtzT6aOuUgOqVFRalOW20SbzRsn5SkI\n",
"name": "example",
"namespace": "examplespace"
}

Accept device

Change device status to accepted.

Authorizations:

jwt

path Parameters

uid

required

string (deviceUID) ^[0-9a-f]{64}$

Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a

Device's UID

Responses

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Get devices

Get a list of devices.

Authorizations:

jwt

query Parameters

filter	string <byte> Filter field receives a JSON object enconded as base64 string for limit a search. The JSON enconded must follow these interafaces: `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<Filter>; }` Examples This is a example to filter and get only the resource what property "confirmed" is "true" `[ { "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" `[ { "type": "property", "params": { "name": "info.id", "operator": "eq", "value": "manjaro" } }, { "type": "property", "params": { "name": "online", "operator": "bool", "value": "true" } }, { "type": "operator", "params": { "name": "and" } } ]`
page	integer >= 1 Default: 1 Page number
per_page	integer [ 1 .. 100 ] Default: 10 Items per page
status	string (deviceStatus) Enum: "accepted" "rejected" "pending" "removed" "unused" Example: status=accepted Device's status
sort_by	string Default: "last_seen" Example: sort_by=name Device's property to sort of
order_by	string Default: "desc" Enum: "asc" "desc" Example: order_by=asc Device's list order

Responses

Response samples

200
401
500

Content type

application/json

[{"uid": "13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a",
"name": "example",
"identity": {"mac": "00:00:00:00:00:00"
},
"info": {"id": "example",
"pretty_name": "linux",
"version": "latest",
"arch": "x86_64",
"platform": "docker"
},
"public_key": "-----BEGIN RSA PUBLIC KEY-----MIIBCgKCAQEA0vH2Bob3mn+uWVaHlOoZD8ai01W6VnRTnXlnHVF7Ny1Vb7pl1Hc4D8bsBhb1vt7aZOYHbCyDR2r5lsrWXCELE8pY8vzfFDA+jNrLbBCJ66E1BcmTqfXCJcLospWD2lIAwU2O7IPxwZujuVkHrF8nYuEFsKeG60QTWNS++RTqydqe2KmFMEdWCQmYPm/ykN871fSR9+PzoRJMYWidY6Szn+X2ardGmS/Ldhl/PEu9h7xjcQXANWz6yV/RVReGVkLcK6TxlfuxgdpbsWAx+cS52P7xWrshNefHqjpdlm3KNbo6vqfTpU8Ld/FFISXXaa1Md5GyAHF+jzuRzQ5z5aKBGwIDAQAB-----END RSA PUBLIC KEY-----",
"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"last_seen": "2020-01-01T00:00:00Z",
"online": true,
"namespace": "examplespace",
"status": "accepted",
"status_update_at": "2020-05-01T00:00:00.000Z",
"created_at": "2020-01-01T00:00:00Z",
"remote_addr": "127.0.0.1",
"position": {"latitude": -31.7566628,
"longitude": -52.322474
},
"tags": ["tag1",
"tag2",
"tag3"
],
"public_url": false,
"acceptable": false
}
]

Get device

Get a device.

Authorizations:

jwt

path Parameters

uid

required

string (deviceUID) ^[0-9a-f]{64}$

Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a

Device's UID

Responses

Response samples

200
401
500

Content type

application/json

{"uid": "13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a",
"name": "example",
"identity": {"mac": "00:00:00:00:00:00"
},
"info": {"id": "example",
"pretty_name": "linux",
"version": "latest",
"arch": "x86_64",
"platform": "docker"
},
"public_key": "-----BEGIN RSA PUBLIC KEY-----MIIBCgKCAQEA0vH2Bob3mn+uWVaHlOoZD8ai01W6VnRTnXlnHVF7Ny1Vb7pl1Hc4D8bsBhb1vt7aZOYHbCyDR2r5lsrWXCELE8pY8vzfFDA+jNrLbBCJ66E1BcmTqfXCJcLospWD2lIAwU2O7IPxwZujuVkHrF8nYuEFsKeG60QTWNS++RTqydqe2KmFMEdWCQmYPm/ykN871fSR9+PzoRJMYWidY6Szn+X2ardGmS/Ldhl/PEu9h7xjcQXANWz6yV/RVReGVkLcK6TxlfuxgdpbsWAx+cS52P7xWrshNefHqjpdlm3KNbo6vqfTpU8Ld/FFISXXaa1Md5GyAHF+jzuRzQ5z5aKBGwIDAQAB-----END RSA PUBLIC KEY-----",
"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"last_seen": "2020-01-01T00:00:00Z",
"online": true,
"namespace": "examplespace",
"status": "accepted",
"status_update_at": "2020-05-01T00:00:00.000Z",
"created_at": "2020-01-01T00:00:00Z",
"remote_addr": "127.0.0.1",
"position": {"latitude": -31.7566628,
"longitude": -52.322474
},
"tags": ["tag1",
"tag2",
"tag3"
],
"public_url": false,
"acceptable": false
}

Delete device

Delete a device.

Authorizations:

jwt

path Parameters

uid

required

string (deviceUID) ^[0-9a-f]{64}$

Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a

Device's UID

Responses

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Update device

Update device's data.

Authorizations:

jwt

path Parameters

uid

required

string (deviceUID) ^[0-9a-f]{64}$

Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a

Device's UID

Request Body schema: application/json

name	string (deviceName) Device's name By default, the name is the device's MAC address when it just added.
public_url	boolean (devicePublicURL) Device's public URL status.

Responses

Request samples

Payload

Content type

application/json

{"name": "example",
"public_url": false
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Update device status

Update device's status.

Authorizations:

jwt

path Parameters

uid required	string (deviceUID) ^[0-9a-f]{64}$ Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a Device's UID
status required	string Enum: "accept" "reject" "pending" "unused" Example: accept Device's status

Responses

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Update device status to offline

Update device's status to offiline.

Authorizations:

jwt

path Parameters

uid

required

string (deviceUID) ^[0-9a-f]{64}$

Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a

Device's UID

Responses

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Get stats ShellHub instance

Get stats ShellHub instance.

Authorizations:

jwt

Responses

Response samples

200
500

Content type

application/json

{"registered_devices": 0,
"online_devices": 0,
"pending_devices": 0,
"rejected_devices": 0,
"active_sessions": 0
}

Create a tag

Authorizations:

jwt

path Parameters

uid

required

string (deviceUID) ^[0-9a-f]{64}$

Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a

Device's UID

Request Body schema: application/json

tag

required

string (tag) [ 3 .. 255 ] characters

Tag's name.

Responses

Request samples

Payload

Content type

application/json

{"tag": "tag1"
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Update tags to device

Authorizations:

jwt

path Parameters

uid

required

string (deviceUID) ^[0-9a-f]{64}$

Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a

Device's UID

Request Body schema: application/json

tags

required

Array of strings (deviceTags) [ 1 .. 3 ] items [ items [ 3 .. 255 ] characters ]

Device's Tags list

Responses

Request samples

Payload

Content type

application/json

{"tags": ["tag1",
"tag2",
"tag3"
]
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Delete a tag from device

Delete a tag from device.

Authorizations:

jwt

path Parameters

uid required	string (deviceUID) ^[0-9a-f]{64}$ Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a Device's UID
tag required	string (tag) [ 3 .. 255 ] characters Example: tag Device's tag name

Responses

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

ssh

Auth SSH public key

Authenticate a SSH public key to ShellHub server.

Authorizations:

jwt

Request Body schema: application/json

fingerprint required	string (publickKeyFingerprint) ^([0-9a-f]{2}:){15}[0-9a-f]{2}$ Public key's fingerprint.
data required	string Public key's data.

Responses

Request samples

Payload

Content type

application/json

{"fingerprint": "48:6e:fc:94:01:01:74:57:eb:57:49:91:15:e4:9c:7a",
"data": "string"
}

Response samples

200
401
500

Content type

application/json

{"signature": "string"
}

Get public keys

Get a list from all public keys.

Authorizations:

jwt

query Parameters

filter

string <byte>

Filter field receives a JSON object enconded as base64 string for limit a search.

The JSON enconded must follow these interafaces:

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<Filter>;
}

Examples

This is a example to filter and get only the resource what property "confirmed" is "true"

[
  {
  "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"

[
  {
    "type": "property",
    "params": {
      "name": "info.id",
      "operator": "eq",
      "value": "manjaro"
    }
  },
  {
    "type": "property",
    "params": {
      "name": "online",
      "operator": "bool",
      "value": "true"
    }
  },
  {
    "type": "operator",
    "params": {
      "name": "and"
    }
  }
]

page

integer >= 1

Default: 1

Page number

per_page

integer [ 1 .. 100 ]

Default: 10

Items per page

Responses

Response samples

200
401
500

Content type

application/json

[{"data": "c3NoLXJzYSBBQUFBQjNOemFDMXljMkVBQUFBREFRQUJBQUFCQVFDWWdqRkNQUWdPejBEZ0VQQUh3blEyMGYzRUlGYjd2SkNtd1YxR25uRTU2K0htaGgyY295c3o5MnZqMW9GeElxQUlKZUZxU3lQNWwzbDZjbkFUVmxhZ2MxR21OQm5vQ0NZSlpicXdOVUFiM3RMTXdiOXBaSGVWMFczWVl4OERBSVVsL2ZYaVVhQTNpQk5BcTFrczFzYjZjbVN1VmYwTVNTSjdoOXU3c2Y2RnkyVmQ0U1FqSGd3YmNvSUY1Q0kyWkZlMEx6NTNWeGQwVlZRZG5ISGNBeldRVFlTMDIxcmVXeG5QR2RRdytmWXpCRWdRMG5sTmFzQXBRc1pVUXRPZ0t4TlNFcVJ0VnJiRUR4WisrTllQaWFuNUdSZ0huZWNUUzBaVGNjZjM4SDZYTms1Qm5XWGlEN2RCWlJBRnZ1UjBkWEF1cU9mYUM3SVl5MVJnS1lkdEsrUnY=",
"fingerprint": "48:6e:fc:94:01:01:74:57:eb:57:49:91:15:e4:9c:7a",
"created_at": "2020-05-01T00:00:00.000Z",
"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"name": "example",
"filter": {"hostname": ".*"
},
"username": ".*"
}
]

Create public key

Create a new public key.

Authorizations:

jwt

Request Body schema: application/json

data required	string (publicKeyData) ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==\|[... Public key's data. The `data` field receives the public key enconded as `base64` string.
required	object or object (publicKeyFilter) 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.
name required	string Public key's name.
username required	string (publicKeyUsername) Public key's regex username. The `username` field define which user, in the device, may be access through this public key.

Responses

Request samples

Payload

Content type

application/json

{"data": "c3NoLXJzYSBBQUFBQjNOemFDMXljMkVBQUFBREFRQUJBQUFCQVFDWWdqRkNQUWdPejBEZ0VQQUh3blEyMGYzRUlGYjd2SkNtd1YxR25uRTU2K0htaGgyY295c3o5MnZqMW9GeElxQUlKZUZxU3lQNWwzbDZjbkFUVmxhZ2MxR21OQm5vQ0NZSlpicXdOVUFiM3RMTXdiOXBaSGVWMFczWVl4OERBSVVsL2ZYaVVhQTNpQk5BcTFrczFzYjZjbVN1VmYwTVNTSjdoOXU3c2Y2RnkyVmQ0U1FqSGd3YmNvSUY1Q0kyWkZlMEx6NTNWeGQwVlZRZG5ISGNBeldRVFlTMDIxcmVXeG5QR2RRdytmWXpCRWdRMG5sTmFzQXBRc1pVUXRPZ0t4TlNFcVJ0VnJiRUR4WisrTllQaWFuNUdSZ0huZWNUUzBaVGNjZjM4SDZYTms1Qm5XWGlEN2RCWlJBRnZ1UjBkWEF1cU9mYUM3SVl5MVJnS1lkdEsrUnY=",
"filter": {"hostname": ".*"
},
"name": "example",
"username": ".*"
}

Response samples

200
401
500

Content type

application/json

{"data": "c3NoLXJzYSBBQUFBQjNOemFDMXljMkVBQUFBREFRQUJBQUFCQVFDWWdqRkNQUWdPejBEZ0VQQUh3blEyMGYzRUlGYjd2SkNtd1YxR25uRTU2K0htaGgyY295c3o5MnZqMW9GeElxQUlKZUZxU3lQNWwzbDZjbkFUVmxhZ2MxR21OQm5vQ0NZSlpicXdOVUFiM3RMTXdiOXBaSGVWMFczWVl4OERBSVVsL2ZYaVVhQTNpQk5BcTFrczFzYjZjbVN1VmYwTVNTSjdoOXU3c2Y2RnkyVmQ0U1FqSGd3YmNvSUY1Q0kyWkZlMEx6NTNWeGQwVlZRZG5ISGNBeldRVFlTMDIxcmVXeG5QR2RRdytmWXpCRWdRMG5sTmFzQXBRc1pVUXRPZ0t4TlNFcVJ0VnJiRUR4WisrTllQaWFuNUdSZ0huZWNUUzBaVGNjZjM4SDZYTms1Qm5XWGlEN2RCWlJBRnZ1UjBkWEF1cU9mYUM3SVl5MVJnS1lkdEsrUnY=",
"fingerprint": "48:6e:fc:94:01:01:74:57:eb:57:49:91:15:e4:9c:7a",
"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"name": "example",
"filter": {"hostname": ".*"
},
"username": ".*"
}

Update public key

Update a public key.

Authorizations:

jwt

path Parameters

fingerprint

required

string (publickKeyFingerprint) ^([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

Public key's fingerprint.

Request Body schema: application/json

name required	string Public key's name.
username required	string Public key's username.
required	object or object (publicKeyFilter) 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.

Responses

Request samples

Payload

Content type

application/json

{"name": "example",
"username": "example",
"filter": {"hostname": ".*"
}
}

Response samples

200
401
500

Content type

application/json

{"data": "c3NoLXJzYSBBQUFBQjNOemFDMXljMkVBQUFBREFRQUJBQUFCQVFDWWdqRkNQUWdPejBEZ0VQQUh3blEyMGYzRUlGYjd2SkNtd1YxR25uRTU2K0htaGgyY295c3o5MnZqMW9GeElxQUlKZUZxU3lQNWwzbDZjbkFUVmxhZ2MxR21OQm5vQ0NZSlpicXdOVUFiM3RMTXdiOXBaSGVWMFczWVl4OERBSVVsL2ZYaVVhQTNpQk5BcTFrczFzYjZjbVN1VmYwTVNTSjdoOXU3c2Y2RnkyVmQ0U1FqSGd3YmNvSUY1Q0kyWkZlMEx6NTNWeGQwVlZRZG5ISGNBeldRVFlTMDIxcmVXeG5QR2RRdytmWXpCRWdRMG5sTmFzQXBRc1pVUXRPZ0t4TlNFcVJ0VnJiRUR4WisrTllQaWFuNUdSZ0huZWNUUzBaVGNjZjM4SDZYTms1Qm5XWGlEN2RCWlJBRnZ1UjBkWEF1cU9mYUM3SVl5MVJnS1lkdEsrUnY=",
"fingerprint": "48:6e:fc:94:01:01:74:57:eb:57:49:91:15:e4:9c:7a",
"created_at": "2020-05-01T00:00:00.000Z",
"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"name": "example",
"filter": {"hostname": ".*"
},
"username": ".*"
}

Delete public key

Delete a public key.

Authorizations:

jwt

path Parameters

fingerprint

required

string (publickKeyFingerprint) ^([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

Public key's fingerprint.

Responses

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Add tag public key

Add a tag to a public key.

Authorizations:

jwt

path Parameters

fingerprint

required

string (publickKeyFingerprint) ^([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

Public key's fingerprint.

Request Body schema: application/json

tag

required

string (tag) [ 3 .. 255 ] characters

Tag's name.

Responses

Request samples

Payload

Content type

application/json

{"tag": "tag"
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Update tags public key

Update all tags in a public key.

Authorizations:

jwt

path Parameters

fingerprint

required

string (publickKeyFingerprint) ^([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

Public key's fingerprint.

Request Body schema: application/json

tags	Array of strings (tag) [ 1 .. 3 ] items unique [ items [ 3 .. 255 ] characters ] Public key's new tags.

Responses

Request samples

Payload

Content type

application/json

{"tags": ["tag1",
"tag2",
"tag3"
]
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Remove tag public key

Remove a tag from public key.

Authorizations:

jwt

path Parameters

fingerprint required	string (publickKeyFingerprint) ^([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 Public key's fingerprint.
tag required	string (tag) [ 3 .. 255 ] characters Example: tag Tag's name.

Responses

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

tags

Add tag public key

Add a tag to a public key.

Authorizations:

jwt

path Parameters

fingerprint

required

string (publickKeyFingerprint) ^([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

Public key's fingerprint.

Request Body schema: application/json

tag

required

string (tag) [ 3 .. 255 ] characters

Tag's name.

Responses

Request samples

Payload

Content type

application/json

{"tag": "tag"
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Update tags public key

Update all tags in a public key.

Authorizations:

jwt

path Parameters

fingerprint

required

string (publickKeyFingerprint) ^([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

Public key's fingerprint.

Request Body schema: application/json

tags	Array of strings (tag) [ 1 .. 3 ] items unique [ items [ 3 .. 255 ] characters ] Public key's new tags.

Responses

Request samples

Payload

Content type

application/json

{"tags": ["tag1",
"tag2",
"tag3"
]
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Remove tag public key

Remove a tag from public key.

Authorizations:

jwt

path Parameters

fingerprint required	string (publickKeyFingerprint) ^([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 Public key's fingerprint.
tag required	string (tag) [ 3 .. 255 ] characters Example: tag Tag's name.

Responses

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Create a tag

Authorizations:

jwt

path Parameters

uid

required

string (deviceUID) ^[0-9a-f]{64}$

Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a

Device's UID

Request Body schema: application/json

tag

required

string (tag) [ 3 .. 255 ] characters

Tag's name.

Responses

Request samples

Payload

Content type

application/json

{"tag": "tag1"
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Update tags to device

Authorizations:

jwt

path Parameters

uid

required

string (deviceUID) ^[0-9a-f]{64}$

Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a

Device's UID

Request Body schema: application/json

tags

required

Array of strings (deviceTags) [ 1 .. 3 ] items [ items [ 3 .. 255 ] characters ]

Device's Tags list

Responses

Request samples

Payload

Content type

application/json

{"tags": ["tag1",
"tag2",
"tag3"
]
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Delete a tag from device

Delete a tag from device.

Authorizations:

jwt

path Parameters

uid required	string (deviceUID) ^[0-9a-f]{64}$ Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a Device's UID
tag required	string (tag) [ 3 .. 255 ] characters Example: tag Device's tag name

Responses

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Get tags

Authorizations:

jwt

Responses

Response samples

200
401
500

Content type

application/json

["tag1",
"tag2",
"tag3",
"tag4"
]

Rename a tag name.

Authorizations:

jwt

path Parameters

tag

required

string (tag) [ 3 .. 255 ] characters

Example: tag

Tag's name.

Request Body schema: application/json

tag	string (tag) [ 3 .. 255 ] characters Tag's name.

Responses

Request samples

Payload

Content type

application/json

{"tag": "tag"
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Delete a tag name.

Authorizations:

jwt

path Parameters

tag

required

string (tag) [ 3 .. 255 ] characters

Example: tag

Tag's name.

Responses

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Create a tag

Authorizations:

jwt

path Parameters

uid

required

string (deviceUID) ^[0-9a-f]{64}$

Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a

Device's UID

Request Body schema: application/json

tag

required

string (tag) [ 3 .. 255 ] characters

Tag's name.

Responses

Request samples

Payload

Content type

application/json

{"tag": "tag1"
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Update tags to container

Authorizations:

jwt

path Parameters

uid

required

string (deviceUID) ^[0-9a-f]{64}$

Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a

Device's UID

Request Body schema: application/json

tags

required

Array of strings (deviceTags) [ 1 .. 3 ] items [ items [ 3 .. 255 ] characters ]

Device's Tags list

Responses

Request samples

Payload

Content type

application/json

{"tags": ["tag1",
"tag2",
"tag3"
]
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Delete a tag from container

Delete a tag from container.

Authorizations:

jwt

path Parameters

uid required	string (deviceUID) ^[0-9a-f]{64}$ Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a Device's UID
tag required	string (tag) [ 3 .. 255 ] characters Example: tag Device's tag name

Responses

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

containers

Get containers

Get a list of containers.

Authorizations:

jwt

query Parameters

filter	string <byte> Filter field receives a JSON object enconded as base64 string for limit a search. The JSON enconded must follow these interafaces: `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<Filter>; }` Examples This is a example to filter and get only the resource what property "confirmed" is "true" `[ { "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" `[ { "type": "property", "params": { "name": "info.id", "operator": "eq", "value": "manjaro" } }, { "type": "property", "params": { "name": "online", "operator": "bool", "value": "true" } }, { "type": "operator", "params": { "name": "and" } } ]`
page	integer >= 1 Default: 1 Page number
per_page	integer [ 1 .. 100 ] Default: 10 Items per page
status	string (deviceStatus) Enum: "accepted" "rejected" "pending" "removed" "unused" Example: status=accepted Container's status
sort_by	string Default: "last_seen" Example: sort_by=name Container's property to sort of
order_by	string Default: "desc" Enum: "asc" "desc" Example: order_by=asc Container's list order

Responses

Response samples

200
401
500

Content type

application/json

[{"uid": "13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a",
"name": "example",
"identity": {"mac": "00:00:00:00:00:00"
},
"info": {"id": "example",
"pretty_name": "linux",
"version": "latest",
"arch": "x86_64",
"platform": "docker"
},
"public_key": "-----BEGIN RSA PUBLIC KEY-----MIIBCgKCAQEA0vH2Bob3mn+uWVaHlOoZD8ai01W6VnRTnXlnHVF7Ny1Vb7pl1Hc4D8bsBhb1vt7aZOYHbCyDR2r5lsrWXCELE8pY8vzfFDA+jNrLbBCJ66E1BcmTqfXCJcLospWD2lIAwU2O7IPxwZujuVkHrF8nYuEFsKeG60QTWNS++RTqydqe2KmFMEdWCQmYPm/ykN871fSR9+PzoRJMYWidY6Szn+X2ardGmS/Ldhl/PEu9h7xjcQXANWz6yV/RVReGVkLcK6TxlfuxgdpbsWAx+cS52P7xWrshNefHqjpdlm3KNbo6vqfTpU8Ld/FFISXXaa1Md5GyAHF+jzuRzQ5z5aKBGwIDAQAB-----END RSA PUBLIC KEY-----",
"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"last_seen": "2020-01-01T00:00:00Z",
"online": true,
"namespace": "examplespace",
"status": "accepted",
"status_update_at": "2020-05-01T00:00:00.000Z",
"created_at": "2020-01-01T00:00:00Z",
"remote_addr": "127.0.0.1",
"position": {"latitude": -31.7566628,
"longitude": -52.322474
},
"tags": ["tag1",
"tag2",
"tag3"
],
"public_url": false,
"acceptable": false
}
]

Get container

Get a container.

Authorizations:

jwt

path Parameters

uid

required

string (deviceUID) ^[0-9a-f]{64}$

Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a

Device's UID

Responses

Response samples

200
401
500

Content type

application/json

{"uid": "13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a",
"name": "example",
"identity": {"mac": "00:00:00:00:00:00"
},
"info": {"id": "example",
"pretty_name": "linux",
"version": "latest",
"arch": "x86_64",
"platform": "docker"
},
"public_key": "-----BEGIN RSA PUBLIC KEY-----MIIBCgKCAQEA0vH2Bob3mn+uWVaHlOoZD8ai01W6VnRTnXlnHVF7Ny1Vb7pl1Hc4D8bsBhb1vt7aZOYHbCyDR2r5lsrWXCELE8pY8vzfFDA+jNrLbBCJ66E1BcmTqfXCJcLospWD2lIAwU2O7IPxwZujuVkHrF8nYuEFsKeG60QTWNS++RTqydqe2KmFMEdWCQmYPm/ykN871fSR9+PzoRJMYWidY6Szn+X2ardGmS/Ldhl/PEu9h7xjcQXANWz6yV/RVReGVkLcK6TxlfuxgdpbsWAx+cS52P7xWrshNefHqjpdlm3KNbo6vqfTpU8Ld/FFISXXaa1Md5GyAHF+jzuRzQ5z5aKBGwIDAQAB-----END RSA PUBLIC KEY-----",
"tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
"last_seen": "2020-01-01T00:00:00Z",
"online": true,
"namespace": "examplespace",
"status": "accepted",
"status_update_at": "2020-05-01T00:00:00.000Z",
"created_at": "2020-01-01T00:00:00Z",
"remote_addr": "127.0.0.1",
"position": {"latitude": -31.7566628,
"longitude": -52.322474
},
"tags": ["tag1",
"tag2",
"tag3"
],
"public_url": false,
"acceptable": false
}

Delete container

Delete a container.

Authorizations:

jwt

path Parameters

uid

required

string (deviceUID) ^[0-9a-f]{64}$

Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a

Device's UID

Responses

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Update container

Update container's data.

Authorizations:

jwt

path Parameters

uid

required

string (deviceUID) ^[0-9a-f]{64}$

Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a

Device's UID

Request Body schema: application/json

name	string (deviceName) Device's name By default, the name is the device's MAC address when it just added.
public_url	boolean (devicePublicURL) Device's public URL status.

Responses

Request samples

Payload

Content type

application/json

{"name": "example",
"public_url": false
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Update container status

Update container's status.

Authorizations:

jwt

path Parameters

uid required	string (deviceUID) ^[0-9a-f]{64}$ Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a Device's UID
status required	string Enum: "accept" "reject" "pending" "unused" Example: accept Container's status

Responses

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Create a tag

Authorizations:

jwt

path Parameters

uid

required

string (deviceUID) ^[0-9a-f]{64}$

Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a

Device's UID

Request Body schema: application/json

tag

required

string (tag) [ 3 .. 255 ] characters

Tag's name.

Responses

Request samples

Payload

Content type

application/json

{"tag": "tag1"
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Update tags to container

Authorizations:

jwt

path Parameters

uid

required

string (deviceUID) ^[0-9a-f]{64}$

Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a

Device's UID

Request Body schema: application/json

tags

required

Array of strings (deviceTags) [ 1 .. 3 ] items [ items [ 3 .. 255 ] characters ]

Device's Tags list

Responses

Request samples

Payload

Content type

application/json

{"tags": ["tag1",
"tag2",
"tag3"
]
}

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}

Delete a tag from container

Delete a tag from container.

Authorizations:

jwt

path Parameters

uid required	string (deviceUID) ^[0-9a-f]{64}$ Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a Device's UID
tag required	string (tag) [ 3 .. 255 ] characters Example: tag Device's tag name

Responses

Response samples

401
500

Content type

application/json

{"message": "missing or malformed jwt or API token"
}