Interacting with the Byos Edge API via CLI – Byos

💡

This article will outline how to interact with the Edge API via the Command Line for use cases where the both i) Edge’s Local Web Dashboard and ii) the Byos Edge Apps are not applicable.

List of API Endpoints

192.168.61.1/api/v1/edge/

Lists the Edge’s Information - Hardware Version, MAC addresses, Edge Model, Serial Number, and Software Version

{
    "hardware_version":"Belledune",
    "mac_addresses":{
        "microsegment":"ca:d4:2f:d9:ce:3b",
        "wifi":"d8:10:68:e1:21:4f"},
    "model":"ENDPOINT",
    "serial":"2A1419AAC2A4E536",
    "software_version":"2.3.1+20250415200739"
}

192.168.61.1/api/v1/connection/

Lists the Edge’s connection details for the current connection

{
    "bss":{
        "bssid":"fc:3f:a6:fc:af:47",
        "frequency":5745,
        "security_mode":"passkey",
        "signal_strength":74,
        "ssid":"Entertainment"},
    "captive_portal_detected":false,
    "connected":true,
    "forwarding":true,
    "internet_access":true,
    "network":{
        "network_id":7,
        "priority":0,
        "ssid":"Entertainment"},
    "network_addresses":{
        "gateway_ip":"192.168.4.1",
        "local_ip":"192.168.4.140"},
    "public_ip":"71.9.236.32",
    "secure_lobby_connections":{
        "local_ip":"10.10.245.249",
        "server_ip":null},
    "secure_lobby_state":"connected",
    "wired_network_addresses":{
        "gateway_ip":null,
        "local_ip":null}
}

192.168.61.1/api/v1/cloud/

Lists the Edge’s Cloud state, including License, Cloud Connection, and Authentication Status

{
    "authenticated":true,
    "connected":true,
    "licensed":true
}

Connect to Network

List all available networks

curl -k -d '' -H "Content-Type: application/json" -X POST https://192.168.61.1/api/v1/scan/

Connect to Wi-Fi

Connecting to a wifi has two steps. First we save the network:

curl -k -d '{"ssid": "MyNetwork", "password": "Password123", "priority": 0}' -H "Content-Type: application/json" -X PUT https://192.168.61.1/api/v1/networks/ https://192.168.61.1/api/v1/networks/

Then we can connect to it:

curl -k -d '{"network_id": RETURNED_NETWORK_ID}' -H "Content-Type: application/json" -X POST https://192.168.61.1/api/v1/connection/ https://192.168.61.1/api/v1/connection/

Activate an Edge

1. Request License Activation Token

curl -k -H "content-type: application/json" -d '{"email": "user@byos.io"}' -X POST https://192.168.61.1/api/v1/tokenrequests/license

2. Input Activation Token to License Edge

curl -k -H "content-type: application/json" -d '{"email": "user@byos.io","machine_name": "Byos Web Dashboard","custom": "Byos Web Dashboard","operating_system": "Any OS","friendly_name": "edge_name","token": "YOUR_MFA_TOKEN_HERE"}' -X POST https://192.168.61.1/api/v1/license/

Authenticate to the Edge

1. Request Sign In Token

First thing you'd need is to request a token to create the user, that can be done like this:

curl -k -d '{"email": "email@example.com"}' -H "Content-Type: application/json" -X POST https://192.168.61.1/api/v1/tokenrequests/user

That will return a token_id something like this, and send a token to the email. Note: the token will only be sent to approved activators.

{
  "token_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

2. Create User

Then, create the user using that token_id and the token received by the email.

curl -k -d '{"custom": "CustomNameForUser", "token_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "operating_system": "macOS 13", "machine_name": "MacBook Pro", "token": "token_from_email"}' -H "Content-Type: application/json" -X POST https://192.168.61.1/api/v1/users/

That will return something like this, you'll use this object in the next endpoint:

{
  "password": "password",
  "id": "some_id_string"
}

3. Authenticate to the Edge

Finally, you can authenticate the device with the password and id:

curl -k -d '{"id": "the_id_string", "password": "the_password"}' -H "Content-Type: application/json" -X POST https://192.168.61.1/api/v1/session/