Husarnet Dashboard client API documentation and manual
This document describes the old API that was tailored for Enterprise customers with very specific needs. The GraphQL API introduced in Husarnet 2.0 has not yet been described publicly. We expect it to be production ready at the end of III quarter of 2023.
Access to (legacy) Husarnet Dashboard API is available only in Public/Enterprise plan and all Self hosted plans.
Thanks to Husarnet Dashboard API you can manage your networks, add devices etc. without doing that manually from a level of http://app.husarnet.com. You can automate those processes by your own scripts that might be useful if you want for example to embed Husarnet functionality into products your are going to provide to a third party.
Authorization
Go to https://app.husarnet.com/api-token to retrieve your Dashboard API token.
GET /api/networks/
This endpoint returns list of networks which are owned by the current user.
$ curl -H 'Authorization: Token xxx...xx' 'https://app.husarnet.com/api/networks/'
where xxx...xx is your Dashboard API token.
Output example:
{
"networks": [
{
"url": "/api/network/12948",
"owner": 2981,
"name": "my-network",
"share_token": "xxxx:xxxxxx:xxxxxxxxxxx_xxxxxxxxxxxx-xx",
"join_code": "fc94:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx/xxxxxxxxxxxxxxxxxxxxxx"
},
{
"url": "/api/network/12248",
"owner": 2981,
"name": "homenet",
"share_token": "xxxx:xxxxxx:xxxxxxxxxxx_xxxxxxxxxxxx-xx",
"join_code": "fc94:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx/xxxxxxxxxxxxxxxxxxxxxx"
}
]
}
POST /api/networks/
Add new, empty network to the Dashboard.
$ curl -H 'Authorization: Token xxx...xx' 'https://app.husarnet.com/api/networks/' --data '{"name": "my-new-net-name"}' -H 'content-type: application/json' -X POST
where xxx...xx is your Dashboard API token.
Output example:
{
"status": "ok",
"network": {
"url": "/api/network/14593",
"owner": 2981,
"name": "my-new-net-name",
"share_token": "xxxx:xxxxxx:xxxxxxxxxxx_xxxxxxxxxxxx-xx",
"join_code": "fc94:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx/xxxxxxxxxxxxxxxxxxxxxx"
}
}
GET /api/network/
This endpoint returns detailed information about a network, including list of members.
$ curl -H 'Authorization: Token xxx...xx' 'https://app.husarnet.com/api/network/12948'
where xxx...xx is your Dashboard API token.
Optionally: Parameter refresh_devices can be set to 1 to force device status refresh. Bare in mind, this operation can be time consuming for larger networks (response time is increased to up to 3 seconds per device).
To avoid long waiting time, one can refresh device status one by one (see: GET /api/status/ for more information).
Sample request to force status refresh:
$ curl -H 'Authorization: Token xxx...xx' 'https://app.husarnet.com/api/network/12948?refresh_devices=1'
Output example:
{
"url": "/api/network/5",
"owner": "user@example.com",
"name": "my-network",
"share_token": "xxxx:xxxxxx:xxxxxxxxxxx_xxxxxxxxxxxx-xx",
"join_code": "fc94:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx/xxxxxxxxxxxxxxxxxxxxxx",
"shares": [
{
"email": "user2@example.com",
"permissions": "member",
},
{
"email": "user3@example.com",
"permissions": "admin",
},
],
"ros-master": 3,
"members": [
{
"id": 18,
"name": "test",
"device-id": "fc94:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx",
"online": false
},
{
"id": 3,
"name": "mymachine",
"device-id": "fc94:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx",
"online": null
}
]
}
DELETE /api/network/
Deletes the network with specified ID.
PUT /api/network/
Changes attributes of the network. Supported attributes: ros-master, name.
curl -H 'authorization: Token yourtoken' 'https://app.husarnet.com/api/network/5' --data '{"name": "newname"}' -H 'content-type: application/json' -X PUT
PATCH /api/network/
Adds or removes members of the network.
{"op": "add-member"}
Add a member to the network specified by the link or (if the device already exists in another network and belongs to the user) by device id.
request body for adding a new device:
{
"op": "add-member",
"link": "https://app.husarnet.com/husarnet/fc94XXXXX",
"name": "[name-of-the-device]",
"is-fully-managed": true/false,
}
arguments:
name- hostname of the device in Husarnet (should match [a-z0-9-]+ regex)is-fully-managed- should Husarnet change hostname of the device to name? true is recommended for ROS.link- URL displayed by husarnet websetup (the link can be aquired via the commandhusarnet websetup)
request body for add an existing device:
{
"op": "add-member",
"device_id": "<IP6_ADDRESS>",
}
If the device doesn't exist or isn't available for the user, a 404 response will be returned by the server.
response:
{"status": "invalid-hostname"}- device name is not a valid hostname{"status": "connect"}- it wasn't possible to contact the device (e.g. it is turned off){"status": "ok"}- the member was added successfully
Warning: this call may take up to 30 seconds (it needs to contact the device), make sure to adjust your timeouts.
{"op": "delete-member"}
Removes a member with specified ID from the network.
request body:
{
"op": "delete-member",
"id": "<id>"
}
{"op": "add-share"}
request body:
{
"op": "add-share",
"email": "<user_email>",
"permissions": "<user_permissions>",
}
Shares a network with a user identified by email address.
Parameters description:
- email: shared user email address
- permissions: either
memberoradmin
Permission classes:
member- can add new devices and delete only the devices that belong to them.admin- can add new devices and delete all devices apart from those that belong to the network owner. Admin is also allowed to share the network and remove shares (can't remove the owner from their network).
{"op": "add-share"}
request body:
{
"op": "remove-share",
"email": "<user_email>",
}
Removes a share from user.
GET /api/status/
Check single device status.
Sample command:
$ curl -H 'Authorization: Token xxx...xx' 'https://app.husarnet.com/api/status/fc94:1c5a:abc:dee:123:4567:244f:55d'
The URL is of format /api/status/<DEVICE_ID> where <DEVICE_ID> is the device's IPv6 address.