You're viewing documentation for the legacy version of Firezone, now End-of-Life. View the latest docs here.

REST API: Devices

This endpoint allows an administrator to manage Devices.

API Documentation

GET /v0/devices

Example

$ curl -i \
  -X GET "https://{firezone_host}/v0/devices" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {api_token}' \

HTTP/1.1 200
Content-Type: application/json; charset=utf-8

{
  "data": [
    {
      "allowed_ips": [
        "0.0.0.0/0",
        "::/0"
      ],
      "description": "factory description",
      "dns": [
        "1.1.1.1",
        "1.0.0.1"
      ],
      "endpoint": "localhost:51820",
      "id": "61d5930b-2b35-44b3-87a9-904e81806728",
      "inserted_at": "2023-03-29T15:11:47.450107Z",
      "ipv4": "100.72.98.240",
      "ipv6": "fd00::39:bf15",
      "latest_handshake": null,
      "mtu": 1280,
      "name": "factory 4421",
      "persistent_keepalive": 25,
      "preshared_key": "32vztut9u6QJG2spTUMnvcb+twugGlT1ikM6AyiPDv8=",
      "public_key": "cGEIZje2ITjFDn96F3bItc5BCl8G1r4SWHH/6QUF4ek=",
      "remote_ip": null,
      "rx_bytes": null,
      "server_public_key": "is+0ov0/SZ9I+qyDD+adVoH9LreWHa85QQgpt6RUtA4=",
      "tx_bytes": null,
      "updated_at": "2023-03-29T15:11:47.450107Z",
      "use_default_allowed_ips": true,
      "use_default_dns": true,
      "use_default_endpoint": true,
      "use_default_mtu": true,
      "use_default_persistent_keepalive": true,
      "user_id": "56062619-2fe2-49de-898c-492d8da794c7"
    },
    {
      "allowed_ips": [
        "0.0.0.0/0",
        "::/0"
      ],
      "description": "factory description",
      "dns": [
        "1.1.1.1",
        "1.0.0.1"
      ],
      "endpoint": "localhost:51820",
      "id": "05db5d62-218e-4139-92f5-0510903ce4f8",
      "inserted_at": "2023-03-29T15:11:47.455712Z",
      "ipv4": "100.111.252.39",
      "ipv6": "fd00::2:456a",
      "latest_handshake": null,
      "mtu": 1280,
      "name": "factory 5411",
      "persistent_keepalive": 25,
      "preshared_key": "78O12m5lG+je3eAqlgJ9pd6d/+VeLjsswsljJFV0jU0=",
      "public_key": "ADOmUjeMl08RgKNhpRaaaHV3YmI9GOVh81zLVLOPk84=",
      "remote_ip": null,
      "rx_bytes": null,
      "server_public_key": "is+0ov0/SZ9I+qyDD+adVoH9LreWHa85QQgpt6RUtA4=",
      "tx_bytes": null,
      "updated_at": "2023-03-29T15:11:47.455712Z",
      "use_default_allowed_ips": true,
      "use_default_dns": true,
      "use_default_endpoint": true,
      "use_default_mtu": true,
      "use_default_persistent_keepalive": true,
      "user_id": "9d3e2da3-bce1-4a03-95cc-d8d0a9797a17"
    },
    {
      "allowed_ips": [
        "0.0.0.0/0",
        "::/0"
      ],
      "description": "factory description",
      "dns": [
        "1.1.1.1",
        "1.0.0.1"
      ],
      "endpoint": "localhost:51820",
      "id": "c865c545-36bd-473e-9c20-9b76766582b2",
      "inserted_at": "2023-03-29T15:11:47.461266Z",
      "ipv4": "100.116.252.229",
      "ipv6": "fd00::7:f039",
      "latest_handshake": null,
      "mtu": 1280,
      "name": "factory 5766",
      "persistent_keepalive": 25,
      "preshared_key": "Dlefj06JAOOCtKxoSlLmvmNXq2zql30FvwDFlEpEISQ=",
      "public_key": "hH9ifN5kI1RtnG54eUXGLEL7Pue9qgGvJ3Gvef7irzU=",
      "remote_ip": null,
      "rx_bytes": null,
      "server_public_key": "is+0ov0/SZ9I+qyDD+adVoH9LreWHa85QQgpt6RUtA4=",
      "tx_bytes": null,
      "updated_at": "2023-03-29T15:11:47.461266Z",
      "use_default_allowed_ips": true,
      "use_default_dns": true,
      "use_default_endpoint": true,
      "use_default_mtu": true,
      "use_default_persistent_keepalive": true,
      "user_id": "47a8eda4-433a-4ce3-a119-720b5d62ddac"
    },
    {
      "allowed_ips": [
        "0.0.0.0/0",
        "::/0"
      ],
      "description": "factory description",
      "dns": [
        "1.1.1.1",
        "1.0.0.1"
      ],
      "endpoint": "localhost:51820",
      "id": "93da8405-217e-40b3-a91b-45d8cd28c2d4",
      "inserted_at": "2023-03-29T15:11:47.467794Z",
      "ipv4": "100.70.183.42",
      "ipv6": "fd00::9:a393",
      "latest_handshake": null,
      "mtu": 1280,
      "name": "factory 1417",
      "persistent_keepalive": 25,
      "preshared_key": "3ipinU20+iTgqCZxSskRPRTBargqtoG73seKz8wZqiE=",
      "public_key": "gzAOiYTnq+rFRBDUbRuJhKXCbe+ULB9xjpCy9l0mBCA=",
      "remote_ip": null,
      "rx_bytes": null,
      "server_public_key": "is+0ov0/SZ9I+qyDD+adVoH9LreWHa85QQgpt6RUtA4=",
      "tx_bytes": null,
      "updated_at": "2023-03-29T15:11:47.467794Z",
      "use_default_allowed_ips": true,
      "use_default_dns": true,
      "use_default_endpoint": true,
      "use_default_mtu": true,
      "use_default_persistent_keepalive": true,
      "user_id": "d8c001ca-ee0f-457f-80a6-802592a7d4ca"
    },
    {
      "allowed_ips": [
        "0.0.0.0/0",
        "::/0"
      ],
      "description": "factory description",
      "dns": [
        "1.1.1.1",
        "1.0.0.1"
      ],
      "endpoint": "localhost:51820",
      "id": "16b319c1-4d8a-478a-88d2-f17056bf1b66",
      "inserted_at": "2023-03-29T15:11:47.473062Z",
      "ipv4": "100.101.38.171",
      "ipv6": "fd00::39:35af",
      "latest_handshake": null,
      "mtu": 1280,
      "name": "factory 4485",
      "persistent_keepalive": 25,
      "preshared_key": "WzNqj8NEQBvYCYjWv4qhuL8sT3n0LVIH52x1xx5U6EE=",
      "public_key": "eD1iqgs712xDZsplZHd7LrNs+WXYshMH99WFkJ0So8o=",
      "remote_ip": null,
      "rx_bytes": null,
      "server_public_key": "is+0ov0/SZ9I+qyDD+adVoH9LreWHa85QQgpt6RUtA4=",
      "tx_bytes": null,
      "updated_at": "2023-03-29T15:11:47.473062Z",
      "use_default_allowed_ips": true,
      "use_default_dns": true,
      "use_default_endpoint": true,
      "use_default_mtu": true,
      "use_default_persistent_keepalive": true,
      "user_id": "605c4532-d516-4b59-a7df-b0479d493cce"
    }
  ]
}

POST /v0/devices

Example

$ curl -i \
  -X POST "https://{firezone_host}/v0/devices" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {api_token}' \
  --data-binary @- << EOF
{
  "device": {
    "allowed_ips": [
      "0.0.0.0/0",
      "::/0",
      "1.1.1.1"
    ],
    "description": "create-description",
    "dns": [
      "9.9.9.8"
    ],
    "endpoint": "9.9.9.9",
    "ipv4": "100.64.0.2",
    "ipv6": "fd00::2",
    "mtu": 999,
    "name": "create-name",
    "persistent_keepalive": 9,
    "preshared_key": "CHqFuS+iL3FTog5F4Ceumqlk0CU4Cl/dyUP/9F9NDnI=",
    "public_key": "CHqFuS+iL3FTog5F4Ceumqlk0CU4Cl/dyUP/9F9NDnI=",
    "use_default_allowed_ips": false,
    "use_default_dns": false,
    "use_default_endpoint": false,
    "use_default_mtu": false,
    "use_default_persistent_keepalive": false,
    "user_id": "95138a8e-c89f-41b4-b62c-a5b8c23a0b8c"
  }
}
EOF

HTTP/1.1 201
Content-Type: application/json; charset=utf-8
Location: /v0/devices/3aefe1b8-d98b-4725-bed3-cad021a13480

{
  "data": {
    "allowed_ips": [
      "0.0.0.0/0",
      "::/0",
      "1.1.1.1"
    ],
    "description": "create-description",
    "dns": [
      "9.9.9.8"
    ],
    "endpoint": "9.9.9.9",
    "id": "3aefe1b8-d98b-4725-bed3-cad021a13480",
    "inserted_at": "2023-03-29T15:11:47.190722Z",
    "ipv4": "100.64.0.2",
    "ipv6": "fd00::2",
    "latest_handshake": null,
    "mtu": 999,
    "name": "create-name",
    "persistent_keepalive": 9,
    "preshared_key": "CHqFuS+iL3FTog5F4Ceumqlk0CU4Cl/dyUP/9F9NDnI=",
    "public_key": "CHqFuS+iL3FTog5F4Ceumqlk0CU4Cl/dyUP/9F9NDnI=",
    "remote_ip": null,
    "rx_bytes": null,
    "server_public_key": "is+0ov0/SZ9I+qyDD+adVoH9LreWHa85QQgpt6RUtA4=",
    "tx_bytes": null,
    "updated_at": "2023-03-29T15:11:47.190722Z",
    "use_default_allowed_ips": false,
    "use_default_dns": false,
    "use_default_endpoint": false,
    "use_default_mtu": false,
    "use_default_persistent_keepalive": false,
    "user_id": "95138a8e-c89f-41b4-b62c-a5b8c23a0b8c"
  }
}

GET /v0/devices/{id}

Example

URI Parameters:

  • id: f85310b7-87b5-4c89-b391-d985f7789007
$ curl -i \
  -X GET "https://{firezone_host}/v0/devices/{id}" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {api_token}' \

HTTP/1.1 200
Content-Type: application/json; charset=utf-8

{
  "data": {
    "allowed_ips": [
      "0.0.0.0/0",
      "::/0"
    ],
    "description": "factory description",
    "dns": [
      "1.1.1.1",
      "1.0.0.1"
    ],
    "endpoint": "localhost:51820",
    "id": "f85310b7-87b5-4c89-b391-d985f7789007",
    "inserted_at": "2023-03-29T15:11:47.299345Z",
    "ipv4": "100.99.173.193",
    "ipv6": "fd00::17:d1a9",
    "latest_handshake": null,
    "mtu": 1280,
    "name": "factory 713",
    "persistent_keepalive": 25,
    "preshared_key": "qrcrAnUh7ryP69SwfseKdBNElOSjOC9/Wv7Z+EBxs50=",
    "public_key": "mLN9py6whsGt+Lg9jP4lX+Cqqlf02plODqWg2UqOmPI=",
    "remote_ip": null,
    "rx_bytes": null,
    "server_public_key": "is+0ov0/SZ9I+qyDD+adVoH9LreWHa85QQgpt6RUtA4=",
    "tx_bytes": null,
    "updated_at": "2023-03-29T15:11:47.299345Z",
    "use_default_allowed_ips": true,
    "use_default_dns": true,
    "use_default_endpoint": true,
    "use_default_mtu": true,
    "use_default_persistent_keepalive": true,
    "user_id": "5f5b582d-9153-46ac-99e5-37a6bc93ce13"
  }
}

PATCH /v0/devices/{id}

Example

URI Parameters:

  • id: 01272ce2-df59-4816-9d82-44830427d757
$ curl -i \
  -X PUT "https://{firezone_host}/v0/devices/{id}" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {api_token}' \
  --data-binary @- << EOF
{
  "device": {
    "allowed_ips": [
      "0.0.0.0/0",
      "::/0",
      "1.1.1.1"
    ],
    "description": "create-description",
    "dns": [
      "9.9.9.8"
    ],
    "endpoint": "9.9.9.9",
    "ipv4": "100.64.0.2",
    "ipv6": "fd00::2",
    "mtu": 999,
    "name": "create-name",
    "persistent_keepalive": 9,
    "preshared_key": "CHqFuS+iL3FTog5F4Ceumqlk0CU4Cl/dyUP/9F9NDnI=",
    "public_key": "CHqFuS+iL3FTog5F4Ceumqlk0CU4Cl/dyUP/9F9NDnI=",
    "use_default_allowed_ips": false,
    "use_default_dns": false,
    "use_default_endpoint": false,
    "use_default_mtu": false,
    "use_default_persistent_keepalive": false
  }
}
EOF

HTTP/1.1 200
Content-Type: application/json; charset=utf-8

{
  "data": {
    "allowed_ips": [
      "0.0.0.0/0",
      "::/0",
      "1.1.1.1"
    ],
    "description": "create-description",
    "dns": [
      "9.9.9.8"
    ],
    "endpoint": "9.9.9.9",
    "id": "01272ce2-df59-4816-9d82-44830427d757",
    "inserted_at": "2023-03-29T15:11:47.264313Z",
    "ipv4": "100.64.0.2",
    "ipv6": "fd00::2",
    "latest_handshake": null,
    "mtu": 999,
    "name": "create-name",
    "persistent_keepalive": 9,
    "preshared_key": "CHqFuS+iL3FTog5F4Ceumqlk0CU4Cl/dyUP/9F9NDnI=",
    "public_key": "CHqFuS+iL3FTog5F4Ceumqlk0CU4Cl/dyUP/9F9NDnI=",
    "remote_ip": null,
    "rx_bytes": null,
    "server_public_key": "is+0ov0/SZ9I+qyDD+adVoH9LreWHa85QQgpt6RUtA4=",
    "tx_bytes": null,
    "updated_at": "2023-03-29T15:11:47.276849Z",
    "use_default_allowed_ips": false,
    "use_default_dns": false,
    "use_default_endpoint": false,
    "use_default_mtu": false,
    "use_default_persistent_keepalive": false,
    "user_id": "3f7c9d0f-fa89-4619-9237-f0215db34e58"
  }
}

DELETE /v0/devices/{id}

Example

URI Parameters:

  • id: 29f86ac9-82e8-4691-aa44-ea396d3af476
$ curl -i \
  -X DELETE "https://{firezone_host}/v0/devices/{id}" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {api_token}' \

HTTP/1.1 204
Last updated: September 25, 2023