Skip to main content
API docs by Redocly

ShellHub Cloud OpenAPI (1.0.0-alpha.3)

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-fA-F]{64}$
Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a

Session's UID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Close session

Close a session.

Authorizations:
jwt
path Parameters
uid
required
string (sessionUID) ^[0-9a-fA-F]{64}$
Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a

Session's UID

Request Body schema: application/json
device
required
string (deviceUID) ^[0-9a-fA-F]{64}$

Device's UID

Responses

Request samples

Content type
application/json
{
  • "device": "13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a"
}

Response samples

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-fA-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

Content type
application/json
{
  • "uid": "string",
  • "message": "string",
  • "width": 0,
  • "height": 0
}

Response samples

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

Content type
application/json
{
  • "action": "allow",
  • "active": true,
  • "filter": {
    },
  • "priority": 1,
  • "source_ip": ".*",
  • "username": ".*"
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
  • "action": "allow",
  • "active": true,
  • "filter": {
    },
  • "priority": 1,
  • "source_ip": ".*",
  • "username": ".*"
}

Get firewall rules

Get a list of firewall rules.

Authorizations:
jwt
query Parameters
page
integer >= 1
Default: 1

Pagination page number

per_page
integer >= 1
Default: 10

Pagination items per page

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get firewall rule

Get a firewall rule.

Authorizations:
jwt
path Parameters
id
required
integer

Firewall rule's ID

Responses

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
  • "action": "allow",
  • "active": true,
  • "filter": {
    },
  • "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

Content type
application/json
{
  • "action": "allow",
  • "active": true,
  • "filter": {
    },
  • "priority": 1,
  • "source_ip": ".*",
  • "username": ".*"
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
  • "action": "allow",
  • "active": true,
  • "filter": {
    },
  • "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

Content type
application/json
{
  • "message": "missing or malformed jwt"
}

Add a tag to firewall rule

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

Content type
application/json
{
  • "tag": "tag1"
}

Response samples

Content type
application/json
{
  • "message": "missing or malformed jwt"
}

Remove a tag from firewall rule

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

Content type
application/json
{
  • "tag": "tag1"
}

Response samples

Content type
application/json
{
  • "message": "missing or malformed jwt"
}

Update tags in firewall rule

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

Content type
application/json
{
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "missing or malformed jwt"
}

Register user

Register user

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-_.@]$

User's username.

password
required
string (userPassword) [ 5 .. 30 ] characters

User's password.

email_marketing
boolean (userMarketing)

User's email marketing option.

Responses

Request samples

Content type
application/json
{
  • "name": "example",
  • "email": "example@example.com",
  • "username": "example",
  • "password": "example",
  • "email_marketing": true
}

Response samples

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

Content type
application/json
{
  • "username": "example"
}

Response samples

Content type
application/json
{
  • "message": "missing or malformed jwt"
}

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

Content type
application/json
{
  • "password": "example",
  • "token": "3dd0d1f8-8246-4519-b11a-a3dd33717f65"
}

Response samples

Content type
application/json
{
  • "message": "missing or malformed jwt"
}

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

Content type
application/json
{
  • "message": "missing or malformed jwt"
}

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-_.@]$

User's username.

Responses

Request samples

Content type
application/json
{
  • "username": "example"
}

Response samples

Content type
application/json
{
  • "message": "missing or malformed jwt"
}

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

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

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

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

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

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

Content type
application/json
{
  • "choices": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "Internal Server Error"
}

Get devices most used

Get the most used devices.

Authorizations:
jwt

Responses

Response samples

Content type
application/json
[
  • {
    }
]

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
}

sessions

Routes related to session resource.

Get session recorded data

Get session recorded data.

Authorizations:
jwt
path Parameters
uid
required
string (sessionUID) ^[0-9a-fA-F]{64}$
Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a

Session's UID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Close session

Close a session.

Authorizations:
jwt
path Parameters
uid
required
string (sessionUID) ^[0-9a-fA-F]{64}$
Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a

Session's UID

Request Body schema: application/json
device
required
string (deviceUID) ^[0-9a-fA-F]{64}$

Device's UID

Responses

Request samples

Content type
application/json
{
  • "device": "13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a"
}

Response samples

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-fA-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

Content type
application/json
{
  • "uid": "string",
  • "message": "string",
  • "width": 0,
  • "height": 0
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Set session record

Define if sessions will be recorded.

Authorizations:
jwt
path Parameters
tenant
required
string (namespaceTenantID) ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-4[0-9a-fA-F]...
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

Content type
application/json
{
  • "session_record": false
}

Response samples

Content type
application/json
{
  • "message": "missing or malformed jwt"
}

Get session record

Get status from if session record feature is enable.

Authorizations:
jwt

Responses

Response samples

Content type
application/json
true

Get sessions

Get a list sessions.

Authorizations:
jwt
query Parameters
page
integer >= 1
Default: 1

Pagination page number

per_page
integer >= 1
Default: 10

Pagination items per page

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get session

Get a session.

Authorizations:
jwt
path Parameters
uid
required
string (sessionUID) ^[0-9a-fA-F]{64}$
Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a

Session's UID

Responses

Response samples

Content type
application/json
{
  • "uid": "13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a",
  • "device_uid": "13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a",
  • "device": {
    },
  • "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": {
    }
}

Set session authentication status

Set session authentication status.

Authorizations:
jwt
path Parameters
uid
required
string (sessionUID) ^[0-9a-fA-F]{64}$
Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a

Session's UID

Request Body schema: application/json
authenticated
boolean

Session's authentication status.

Responses

Request samples

Content type
application/json
{
  • "authenticated": true
}

Response samples

Content type
application/json
{
  • "message": "missing or malformed jwt"
}

users

Routes related to users resource.

Register user

Register user

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-_.@]$

User's username.

password
required
string (userPassword) [ 5 .. 30 ] characters

User's password.

email_marketing
boolean (userMarketing)

User's email marketing option.

Responses

Request samples

Content type
application/json
{
  • "name": "example",
  • "email": "example@example.com",
  • "username": "example",
  • "password": "example",
  • "email_marketing": true
}

Response samples

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

Content type
application/json
{
  • "username": "example"
}

Response samples

Content type
application/json
{
  • "message": "missing or malformed jwt"
}

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

Content type
application/json
{
  • "password": "example",
  • "token": "3dd0d1f8-8246-4519-b11a-a3dd33717f65"
}

Response samples

Content type
application/json
{
  • "message": "missing or malformed jwt"
}

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

Content type
application/json
{
  • "message": "missing or malformed jwt"
}

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-_.@]$

User's username.

Responses

Request samples

Content type
application/json
{
  • "username": "example"
}

Response samples

Content type
application/json
{
  • "message": "missing or malformed jwt"
}

Login

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-_.@]$

User's username.

password
required
string (userPassword) [ 5 .. 30 ] characters

User's password.

Responses

Request samples

Content type
application/json
{
  • "username": "example",
  • "password": "example"
}

Response samples

Content type
application/json
{
  • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJleGFtcGxlIiwibmFtZSI6ImV4YW1wbGUiLCJpYXQiOjE1MTYyMzkwMjJ9.zqCt70KspnNnitZlv89hDbFZ5iGMMRUn0wFEmmlY-to",
  • "id": "507f1f77bcf86cd799439011",
  • "user": "example",
  • "name": "example",
  • "email": "example@example.com",
  • "tenant": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
  • "role": "administrator"
}

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-_.@]$

User's username.

password
required
string (userPassword) [ 5 .. 30 ] characters

User's password.

Responses

Request samples

Content type
application/json
{
  • "username": "example",
  • "password": "example"
}

Response samples

Content type
application/json
{
  • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJleGFtcGxlIiwibmFtZSI6ImV4YW1wbGUiLCJpYXQiOjE1MTYyMzkwMjJ9.zqCt70KspnNnitZlv89hDbFZ5iGMMRUn0wFEmmlY-to",
  • "id": "507f1f77bcf86cd799439011",
  • "user": "example",
  • "name": "example",
  • "email": "example@example.com",
  • "tenant": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
  • "role": "administrator"
}

Get user info

Authorizations:
jwt

Responses

Response samples

Content type
application/json
{
  • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJleGFtcGxlIiwibmFtZSI6ImV4YW1wbGUiLCJpYXQiOjE1MTYyMzkwMjJ9.zqCt70KspnNnitZlv89hDbFZ5iGMMRUn0wFEmmlY-to",
  • "id": "507f1f77bcf86cd799439011",
  • "user": "example",
  • "name": "example",
  • "email": "example@example.com",
  • "tenant": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
  • "role": "administrator"
}

Get token

Get a token from its tenant.

Authorizations:
jwt
path Parameters
tenant
string

Tenant

Responses

Response samples

Content type
application/json
{
  • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJleGFtcGxlIiwibmFtZSI6ImV4YW1wbGUiLCJpYXQiOjE1MTYyMzkwMjJ9.zqCt70KspnNnitZlv89hDbFZ5iGMMRUn0wFEmmlY-to",
  • "id": "507f1f77bcf86cd799439011",
  • "user": "example",
  • "name": "example",
  • "email": "example@example.com",
  • "tenant": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
  • "role": "administrator"
}

Update user data

Update user's data.

Authorizations:
jwt
path Parameters
id
required
string

User's ID.

Request Body schema: application/json
name
required
string

User's name.

email
required
string <email>

User's e-mail.

username
required
string

User's username.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "email": "user@example.com",
  • "username": "string"
}

Response samples

Content type
application/json
[
  • "username",
  • "email"
]

Update user password

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

Content type
application/json
{
  • "current_password": "string",
  • "new_password": "string"
}

Response samples

Content type
application/json
{
  • "message": "missing or malformed jwt"
}

Set session record

Define if sessions will be recorded.

Authorizations:
jwt
path Parameters
tenant
required
string (namespaceTenantID) ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-4[0-9a-fA-F]...
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

Content type
application/json
{
  • "session_record": false
}

Response samples

Content type
application/json
{
  • "message": "missing or malformed jwt"
}

Get session record

Get status from if session record feature is enable.

Authorizations:
jwt

Responses

Response samples

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

Content type
application/json
{
  • "action": "allow",
  • "active": true,
  • "filter": {
    },
  • "priority": 1,
  • "source_ip": ".*",
  • "username": ".*"
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
  • "action": "allow",
  • "active": true,
  • "filter": {
    },
  • "priority": 1,
  • "source_ip": ".*",
  • "username": ".*"
}

Get firewall rules

Get a list of firewall rules.

Authorizations:
jwt
query Parameters
page
integer >= 1
Default: 1

Pagination page number

per_page
integer >= 1
Default: 10

Pagination items per page

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get firewall rule

Get a firewall rule.

Authorizations:
jwt
path Parameters
id
required
integer

Firewall rule's ID

Responses

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
  • "action": "allow",
  • "active": true,
  • "filter": {
    },
  • "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

Content type
application/json
{
  • "action": "allow",
  • "active": true,
  • "filter": {
    },
  • "priority": 1,
  • "source_ip": ".*",
  • "username": ".*"
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
  • "action": "allow",
  • "active": true,
  • "filter": {
    },
  • "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

Content type
application/json
{
  • "message": "missing or malformed jwt"
}

Add a tag to firewall rule

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

Content type
application/json
{
  • "tag": "tag1"
}

Response samples

Content type
application/json
{
  • "message": "missing or malformed jwt"
}

Remove a tag from firewall rule

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

Content type
application/json
{
  • "tag": "tag1"
}

Response samples

Content type
application/json
{
  • "message": "missing or malformed jwt"
}

Update tags in firewall rule

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

Content type
application/json
{
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "missing or malformed jwt"
}

announcements

Routes related to announcements resource

List announcements

List the announcements posted by ShellHub Cloud.

query Parameters
page
integer >= 1
Default: 1

Pagination page number

per_page
integer >= 1
Default: 10

Pagination items per page

order_by
string
Default: "desc"
Enum: "asc" "desc"
Example: order_by=asc

Announcements' list order.

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Get a announcement

Get a announcement.

path Parameters
uuid
required
string (announcementUUID) ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-4[0-9a-fA-F]...
Example: 3dd0d1f8-8246-4519-b11a-a3dd33717f65

Announcement UUID.

Responses

Response samples

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"
}

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

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

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

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

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

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

Content type
application/json
{
  • "choices": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "Internal Server Error"
}

Get devices most used

Get the most used devices.

Authorizations:
jwt

Responses

Response samples

Content type
application/json
[
  • {
    }
]

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
}

Get info

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

query Parameters
agent_version
string

Agent's version.

Responses

Response samples

Content type
application/json
{
  • "version": "latest",
  • "endpoints": {
    }
}

external

Login

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-_.@]$

User's username.

password
required
string (userPassword) [ 5 .. 30 ] characters

User's password.

Responses

Request samples

Content type
application/json
{
  • "username": "example",
  • "password": "example"
}

Response samples

Content type
application/json
{
  • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJleGFtcGxlIiwibmFtZSI6ImV4YW1wbGUiLCJpYXQiOjE1MTYyMzkwMjJ9.zqCt70KspnNnitZlv89hDbFZ5iGMMRUn0wFEmmlY-to",
  • "id": "507f1f77bcf86cd799439011",
  • "user": "example",
  • "name": "example",
  • "email": "example@example.com",
  • "tenant": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
  • "role": "administrator"
}

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-_.@]$

User's username.

password
required
string (userPassword) [ 5 .. 30 ] characters

User's password.

Responses

Request samples

Content type
application/json
{
  • "username": "example",
  • "password": "example"
}

Response samples

Content type
application/json
{
  • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJleGFtcGxlIiwibmFtZSI6ImV4YW1wbGUiLCJpYXQiOjE1MTYyMzkwMjJ9.zqCt70KspnNnitZlv89hDbFZ5iGMMRUn0wFEmmlY-to",
  • "id": "507f1f77bcf86cd799439011",
  • "user": "example",
  • "name": "example",
  • "email": "example@example.com",
  • "tenant": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
  • "role": "administrator"
}

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 (namespaceTenantID) ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-4[0-9a-fA-F]...

Namespace's tenant ID

Responses

Request samples

Content type
application/json
{
  • "info": {
    },
  • "sessions": [
    ],
  • "hostname": "string",
  • "identity": {
    },
  • "public_key": "string",
  • "tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65"
}

Response samples

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 (namespaceTenantID) ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-4[0-9a-fA-F]...

Namespace's tenant ID

Responses

Request samples

Content type
application/json
{
  • "info": {
    },
  • "sessions": [
    ],
  • "hostname": "string",
  • "identity": {
    },
  • "public_key": "string",
  • "tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65"
}

Response samples

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

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

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-fA-F]{64}$
Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a

Device's UID

Responses

Response samples

Content type
application/json
{
  • "message": "missing or malformed jwt"
}

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 (namespaceTenantID) ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-4[0-9a-fA-F]...

Namespace's tenant ID

Responses

Request samples

Content type
application/json
{
  • "info": {
    },
  • "sessions": [
    ],
  • "hostname": "string",
  • "identity": {
    },
  • "public_key": "string",
  • "tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65"
}

Response samples

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 (namespaceTenantID) ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-4[0-9a-fA-F]...

Namespace's tenant ID

Responses

Request samples

Content type
application/json
{
  • "info": {
    },
  • "sessions": [
    ],
  • "hostname": "string",
  • "identity": {
    },
  • "public_key": "string",
  • "tenant_id": "3dd0d1f8-8246-4519-b11a-a3dd33717f65"
}

Response samples

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-fA-F]{64}$
Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a

Device's UID

Responses

Response samples

Content type
application/json
{
  • "message": "missing or malformed jwt"
}

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

Pagination page number

per_page
integer >= 1
Default: 10

Pagination items per page

status
string (deviceStatus)
Enum: "accepted" "rejected" "pending" "removed" "unused"
Example: status=accepted

Device's status

sort_by
string
Example: sort_by=name

Device's property to sort of

order_by
string
Enum: "asc" "desc"
Example: order_by=asc

Device's list order

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get device

Get a device.

Authorizations:
jwt
path Parameters
uid
required
string (deviceUID) ^[0-9a-fA-F]{64}$
Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a

Device's UID

Responses

Response samples

Content type
application/json
{
  • "uid": "13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a",
  • "name": "example",
  • "identity": {
    },
  • "info": {
    },
  • "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": {
    },
  • "tags": [
    ],
  • "public_url": false,
  • "acceptable": false
}

Delete device

Delete a device.

Authorizations:
jwt
path Parameters
uid
required
string (deviceUID) ^[0-9a-fA-F]{64}$
Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a

Device's UID

Responses

Response samples

Content type
application/json
{
  • "message": "missing or malformed jwt"
}

Update device

Update device's data.

Authorizations:
jwt
path Parameters
uid
required
string (deviceUID) ^[0-9a-fA-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

Content type
application/json
{
  • "name": "example",
  • "public_url": false
}

Response samples

Content type
application/json
{
  • "message": "missing or malformed jwt"
}

Update device status

Update device's status.

Authorizations:
jwt
path Parameters
uid
required
string (deviceUID) ^[0-9a-fA-F]{64}$
Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a

Device's UID

status
required
string
Enum: "accept" "reject" "pending" "unused"
Example: accept

Device's status

Responses

Response samples

Content type
application/json
{
  • "message": "missing or malformed jwt"
}

Update device status to offline

Update device's status to offiline.

Authorizations:
jwt
path Parameters
uid
required
string (deviceUID) ^[0-9a-fA-F]{64}$
Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a

Device's UID

Responses

Response samples

Content type
application/json
{
  • "message": "missing or malformed jwt"
}

Get stats ShellHub instance

Get stats ShellHub instance.

Authorizations:
jwt

Responses

Response samples

Content type
application/json
{
  • "registered_devices": 0,
  • "online_devices": 0,
  • "pending_devices": 0,
  • "rejected_devices": 0,
  • "active_sessions": 0
}

Create a tag

Create a tag

Authorizations:
jwt
path Parameters
uid
required
string (deviceUID) ^[0-9a-fA-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

Content type
application/json
{
  • "tag": "tag1"
}

Response samples

Content type
application/json
{
  • "message": "missing or malformed jwt"
}

Update tags to device

Update tags to device

Authorizations:
jwt
path Parameters
uid
required
string (deviceUID) ^[0-9a-fA-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

Content type
application/json
{
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "missing or malformed jwt"
}

Delete a tag from device

Delete a tag from device.

Authorizations:
jwt
path Parameters
uid
required
string (deviceUID) ^[0-9a-fA-F]{64}$
Example: 13b0c8ea878e61ff849db69461795006a9594c8f6a6390ce0000100b0c9d7d0a

Device's UID

tag
required
string (tag) [ 3 .. 255 ] characters
Example: tag

Device's tag name

Responses

Response samples

Content type
application/json
{
  • "message": "missing or malformed jwt"
}

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

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

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

Pagination page number

per_page
integer >= 1
Default: 10

Pagination items per page

Responses

Response samples

Content type
application/json
[
  • {
    }
]

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

Content type
application/json
{
  • "data": "c3NoLXJzYSBBQUFBQjNOemFDMXljMkVBQUFBREFRQUJBQUFCQVFDWWdqRkNQUWdPejBEZ0VQQUh3blEyMGYzRUlGYjd2SkNtd1YxR25uRTU2K0htaGgyY295c3o5MnZqMW9GeElxQUlKZUZxU3lQNWwzbDZjbkFUVmxhZ2MxR21OQm5vQ0NZSlpicXdOVUFiM3RMTXdiOXBaSGVWMFczWVl4OERBSVVsL2ZYaVVhQTNpQk5BcTFrczFzYjZjbVN1VmYwTVNTSjdoOXU3c2Y2RnkyVmQ0U1FqSGd3YmNvSUY1Q0kyWkZlMEx6NTNWeGQwVlZRZG5ISGNBeldRVFlTMDIxcmVXeG5QR2RRdytmWXpCRWdRMG5sTmFzQXBRc1pVUXRPZ0t4TlNFcVJ0VnJiRUR4WisrTllQaWFuNUdSZ0huZWNUUzBaVGNjZjM4SDZYTms1Qm5XWGlEN2RCWlJBRnZ1UjBkWEF1cU9mYUM3SVl5MVJnS1lkdEsrUnY=",
  • "filter": {
    },
  • "name": "example",
  • "username": ".*"
}

Response samples

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": {
    },
  • "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

Content type
application/json
{
  • "name": "example",
  • "username": "example",
  • "filter": {
    }
}

Response samples

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": {
    },
  • "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

Content type
application/json
{
  • "message": "missing or malformed jwt"
}

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

Content type
application/json
{
  • "tag": "tag"
}

Response samples

Content type
application/json
{
  • "message": "missing or malformed jwt"
}

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

Content type
application/json
{
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "missing or malformed jwt"
}

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

Content type
application/json
{
  • "message": "missing or malformed jwt"
}

namespaces

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 (namespaceTenantID) ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-4[0-9a-fA-F]...
Example: 3dd0d1f8-8246-4519-b11a-a3dd33717f65

Namespace's tenant ID

Responses

Response samples

Content type
application/json
{
  • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJleGFtcGxlIiwibmFtZSI6ImV4YW1wbGUiLCJpYXQiOjE1MTYyMzkwMjJ9.zqCt70KspnNnitZlv89hDbFZ5iGMMRUn0wFEmmlY-to",
  • "id": "507f1f77bcf86cd799439011",
  • "user": "example",
  • "name": "example",
  • "email": "example@example.com",
  • "tenant": "3dd0d1f8-8246-4519-b11a-a3dd33717f65",
  • "role": "administrator"
}

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

Pagination page number

per_page
integer >= 1
Default: 10

Pagination items per page

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create namespace

Create a namespace.

Authorizations:
jwt
Request Body schema: application/json
name
required
string (namespaceName)

Namespace's name