IoT Devices

Control which specific IoT devices are allowed to connect to a Hub

List devices

GET

https://api.scaleway.com

/iot/v1/regions/{region}/devices

List all devices in the specified region. By default, returned devices are ordered by creation date in ascending order, though this can be modified via the order_by field.

List devices › path Parameters

region

string · enum · required

The region you want to target

Enum values:

fr-par

List devices › query Parameters

page

integer · int32

Page number to return, from the paginated results.

page_size

integer · uint32

Number of devices to return within a page. Maximum value is 100.

order_by

string · enum

Ordering of requested devices.

Enum values:

name_asc

name_desc

status_asc

status_desc

hub_id_asc

hub_id_desc

created_at_asc

created_at_desc

Default: name_asc

name

string

Name to filter for, only devices with this name will be returned.

hub_id

string

Hub ID to filter for, only devices attached to this Hub will be returned.

allow_insecure

boolean

Defines whether to filter the allow_insecure flag.

status

string · enum

Device status (enabled, disabled, etc.).

Enum values:

unknown

error

enabled

disabled

Default: unknown

List devices › Responses

200

scaleway.iot.v1.ListDevicesResponse

total_count

integer · uint32

Total number of devices.

scaleway.iot.v1.Device[]

Page of devices.

GET/iot/v1/regions/{region}/devices

curl -X GET \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  "https://api.scaleway.com/iot/v1/regions/{region}/devices"

Example Responses

{
  "total_count": 0,
  "devices": [
    {
      "id": "id",
      "name": "name",
      "description": "description",
      "status": "unknown",
      "hub_id": "hub_id",
      "last_activity_at": "2022-03-22T12:34:56.123456Z",
      "is_connected": true,
      "allow_insecure": true,
      "allow_multiple_connections": true,
      "message_filters": {
        "publish": {
          "policy": "unknown",
          "topics": [
            "string"
          ]
        },
        "subscribe": {
          "policy": "unknown",
          "topics": [
            "string"
          ]
        }
      },
      "has_custom_certificate": true,
      "created_at": "2022-03-22T12:34:56.123456Z",
      "updated_at": "2022-03-22T12:34:56.123456Z",
      "region": "region"
    }
  ]
}

json

application/json

Add a device

POST

https://api.scaleway.com

/iot/v1/regions/{region}/devices

Attach a device to a given Hub.

Add a device › path Parameters

region

string · enum · required

The region you want to target

Enum values:

fr-par

Add a device › Request Body

name

string · required

Device name.

hub_id

string · required

Hub ID of the device.

allow_insecure

boolean

Defines whether to allow plain and server-authenticated SSL connections in addition to mutually-authenticated ones.

allow_multiple_connections

boolean

Defines whether to allow multiple physical devices to connect with this device's credentials.

object

Filter-sets to authorize or deny the device to publish/subscribe to specific topics.

description

string

Device description.

Add a device › Responses

200

scaleway.iot.v1.CreateDeviceResponse

object

Information related to the created device.

object

Device certificate.

POST/iot/v1/regions/{region}/devices

curl -X POST \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "allow_insecure": false,
    "allow_multiple_connections": false,
    "hub_id": "string",
    "name": "string"
  }' \
  "https://api.scaleway.com/iot/v1/regions/{region}/devices"

Example Request Body

{
  "name": "name",
  "hub_id": "hub_id",
  "allow_insecure": true,
  "allow_multiple_connections": true,
  "message_filters": {
    "publish": {
      "policy": "unknown",
      "topics": [
        "string"
      ]
    },
    "subscribe": {
      "policy": "unknown",
      "topics": [
        "string"
      ]
    }
  },
  "description": "description"
}

json

Example Responses

{
  "device": {
    "id": "id",
    "name": "name",
    "description": "description",
    "status": "unknown",
    "hub_id": "hub_id",
    "last_activity_at": "2022-03-22T12:34:56.123456Z",
    "is_connected": true,
    "allow_insecure": true,
    "allow_multiple_connections": true,
    "message_filters": {
      "publish": {
        "policy": "unknown",
        "topics": [
          "string"
        ]
      },
      "subscribe": {
        "policy": "unknown",
        "topics": [
          "string"
        ]
      }
    },
    "has_custom_certificate": true,
    "created_at": "2022-03-22T12:34:56.123456Z",
    "updated_at": "2022-03-22T12:34:56.123456Z",
    "region": "region"
  },
  "certificate": {
    "crt": "crt",
    "key": "key"
  }
}

json

application/json

Get a device

GET

https://api.scaleway.com

/iot/v1/regions/{region}/devices/{device_id}

Retrieve information about an existing device, specified by its device ID. Its full details, including name, status and ID, are returned in the response object.

Get a device › path Parameters

region

string · enum · required

The region you want to target

Enum values:

fr-par

device_id

string · required

Device ID.

Get a device › Responses

200

scaleway.iot.v1.Device

id

string

Device ID, also used as MQTT Client ID or username.

name

string

Device name.

description

string

Device description.

status

string · enum

Device status.

Enum values:

unknown

error

enabled

disabled

Default: unknown

hub_id

string

Hub ID.

last_activity_at

string · date-time

Last connection/activity date of a device. (RFC 3339 format)

is_connected

boolean

Defines whether the device is connected to the Hub.

allow_insecure

boolean

Defines whether to allow the device to connect to the Hub without TLS mutual authentication.

allow_multiple_connections

boolean

Defines whether to allow multiple physical devices to connect to the Hub with this device's credentials.

object

Filter-sets to restrict the topics the device can publish/subscribe to.

has_custom_certificate

boolean

Defines whether the device was assigned a custom certificate. Assigning a custom certificate allows a device to authenticate using that specific certificate without checking the Hub's CA certificate.

created_at

string · date-time

Date at which the device was added. (RFC 3339 format)

updated_at

string · date-time

Date at which the device was last modified. (RFC 3339 format)

region

string

Region of the device.

GET/iot/v1/regions/{region}/devices/{device_id}

curl -X GET \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  "https://api.scaleway.com/iot/v1/regions/{region}/devices/{device_id}"

Example Responses

{
  "id": "id",
  "name": "name",
  "description": "description",
  "status": "unknown",
  "hub_id": "hub_id",
  "last_activity_at": "2022-03-22T12:34:56.123456Z",
  "is_connected": true,
  "allow_insecure": true,
  "allow_multiple_connections": true,
  "message_filters": {
    "publish": {
      "policy": "unknown",
      "topics": [
        "string"
      ]
    },
    "subscribe": {
      "policy": "unknown",
      "topics": [
        "string"
      ]
    }
  },
  "has_custom_certificate": true,
  "created_at": "2022-03-22T12:34:56.123456Z",
  "updated_at": "2022-03-22T12:34:56.123456Z",
  "region": "region"
}

json

application/json

Remove a device

DELETE

https://api.scaleway.com

/iot/v1/regions/{region}/devices/{device_id}

Remove a specific device from the specific Hub it is attached to.

Remove a device › path Parameters

region

string · enum · required

The region you want to target

Enum values:

fr-par

device_id

string · required

Device ID.

Remove a device › Responses

No data returned

Update a device

PATCH

https://api.scaleway.com

/iot/v1/regions/{region}/devices/{device_id}

Update the parameters of an existing device, specified by its device ID.

Update a device › path Parameters

region

string · enum · required

The region you want to target

Enum values:

fr-par

device_id

string · required

Device ID.

Update a device › Request Body

description

string

Description for the device.

allow_insecure

boolean

Defines whether to allow plain and server-authenticated SSL connections in addition to mutually-authenticated ones.

allow_multiple_connections

boolean

Defines whether to allow multiple physical devices to connect with this device's credentials.

object

Filter-sets to restrict the topics the device can publish/subscribe to.

hub_id

string

Change Hub for this device, additional fees may apply, see IoT Hub pricing.

Update a device › Responses

200

scaleway.iot.v1.Device

id

string

Device ID, also used as MQTT Client ID or username.

name

string

Device name.

description

string

Device description.

status

string · enum

Device status.

Enum values:

unknown

error

enabled

disabled

Default: unknown

hub_id

string

Hub ID.

last_activity_at

string · date-time

Last connection/activity date of a device. (RFC 3339 format)

is_connected

boolean

Defines whether the device is connected to the Hub.

allow_insecure

boolean

Defines whether to allow the device to connect to the Hub without TLS mutual authentication.

allow_multiple_connections

boolean

Defines whether to allow multiple physical devices to connect to the Hub with this device's credentials.

object

Filter-sets to restrict the topics the device can publish/subscribe to.

has_custom_certificate

boolean

Defines whether the device was assigned a custom certificate. Assigning a custom certificate allows a device to authenticate using that specific certificate without checking the Hub's CA certificate.

created_at

string · date-time

Date at which the device was added. (RFC 3339 format)

updated_at

string · date-time

Date at which the device was last modified. (RFC 3339 format)

region

string

Region of the device.

PATCH/iot/v1/regions/{region}/devices/{device_id}

curl -X PATCH \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "https://api.scaleway.com/iot/v1/regions/{region}/devices/{device_id}"

Example Request Body

{
  "description": "description",
  "allow_insecure": true,
  "allow_multiple_connections": true,
  "message_filters": {
    "publish": {
      "policy": "unknown",
      "topics": [
        "string"
      ]
    },
    "subscribe": {
      "policy": "unknown",
      "topics": [
        "string"
      ]
    }
  },
  "hub_id": "hub_id"
}

json

Example Responses

{
  "id": "id",
  "name": "name",
  "description": "description",
  "status": "unknown",
  "hub_id": "hub_id",
  "last_activity_at": "2022-03-22T12:34:56.123456Z",
  "is_connected": true,
  "allow_insecure": true,
  "allow_multiple_connections": true,
  "message_filters": {
    "publish": {
      "policy": "unknown",
      "topics": [
        "string"
      ]
    },
    "subscribe": {
      "policy": "unknown",
      "topics": [
        "string"
      ]
    }
  },
  "has_custom_certificate": true,
  "created_at": "2022-03-22T12:34:56.123456Z",
  "updated_at": "2022-03-22T12:34:56.123456Z",
  "region": "region"
}

json

application/json

Get a device's certificate

GET

https://api.scaleway.com

/iot/v1/regions/{region}/devices/{device_id}/certificate

Get information for a particular PEM-encoded certificate, specified by the device ID. The response returns full details of the device, including its type of certificate.

Get a device's certificate › path Parameters

region

string · enum · required

The region you want to target

Enum values:

fr-par

device_id

string · required

Device ID.

Get a device's certificate › Responses

200

scaleway.iot.v1.GetDeviceCertificateResponse

object

Information related to the created device.

certificate_pem

string

Device certificate.

GET/iot/v1/regions/{region}/devices/{device_id}/certificate

curl -X GET \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  "https://api.scaleway.com/iot/v1/regions/{region}/devices/{device_id}/certificate"

Example Responses

{
  "device": {
    "id": "id",
    "name": "name",
    "description": "description",
    "status": "unknown",
    "hub_id": "hub_id",
    "last_activity_at": "2022-03-22T12:34:56.123456Z",
    "is_connected": true,
    "allow_insecure": true,
    "allow_multiple_connections": true,
    "message_filters": {
      "publish": {
        "policy": "unknown",
        "topics": [
          "string"
        ]
      },
      "subscribe": {
        "policy": "unknown",
        "topics": [
          "string"
        ]
      }
    },
    "has_custom_certificate": true,
    "created_at": "2022-03-22T12:34:56.123456Z",
    "updated_at": "2022-03-22T12:34:56.123456Z",
    "region": "region"
  },
  "certificate_pem": "certificate_pem"
}

json

application/json

Set a custom certificate on a device

PUT

https://api.scaleway.com

/iot/v1/regions/{region}/devices/{device_id}/certificate

Switch the existing certificate of a given device with an EM-encoded custom certificate.

Set a custom certificate on a device › path Parameters

region

string · enum · required

The region you want to target

Enum values:

fr-par

device_id

string · required

Device ID.

Set a custom certificate on a device › Request Body

certificate_pem

string · required

PEM-encoded custom certificate.

Set a custom certificate on a device › Responses

200

scaleway.iot.v1.SetDeviceCertificateResponse

scaleway.iot.v1.Device

certificate_pem

string

PUT/iot/v1/regions/{region}/devices/{device_id}/certificate

curl -X PUT \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"certificate_pem":"string"}' \
  "https://api.scaleway.com/iot/v1/regions/{region}/devices/{device_id}/certificate"

Example Request Body

{
  "certificate_pem": "certificate_pem"
}

json

Example Responses

{
  "device": {
    "id": "id",
    "name": "name",
    "description": "description",
    "status": "unknown",
    "hub_id": "hub_id",
    "last_activity_at": "2022-03-22T12:34:56.123456Z",
    "is_connected": true,
    "allow_insecure": true,
    "allow_multiple_connections": true,
    "message_filters": {
      "publish": {
        "policy": "unknown",
        "topics": [
          "string"
        ]
      },
      "subscribe": {
        "policy": "unknown",
        "topics": [
          "string"
        ]
      }
    },
    "has_custom_certificate": true,
    "created_at": "2022-03-22T12:34:56.123456Z",
    "updated_at": "2022-03-22T12:34:56.123456Z",
    "region": "region"
  },
  "certificate_pem": "certificate_pem"
}

json

application/json

Disable a device

POST

https://api.scaleway.com

/iot/v1/regions/{region}/devices/{device_id}/disable

Disable an existing device, specified by its device ID.

Disable a device › path Parameters

region

string · enum · required

The region you want to target

Enum values:

fr-par

device_id

string · required

Device ID.

Disable a device › Request Body

Disable a device › Responses

200

scaleway.iot.v1.Device

id

string

Device ID, also used as MQTT Client ID or username.

name

string

Device name.

description

string

Device description.

status

string · enum

Device status.

Enum values:

unknown

error

enabled

disabled

Default: unknown

hub_id

string

Hub ID.

last_activity_at

string · date-time

Last connection/activity date of a device. (RFC 3339 format)

is_connected

boolean

Defines whether the device is connected to the Hub.

allow_insecure

boolean

Defines whether to allow the device to connect to the Hub without TLS mutual authentication.

allow_multiple_connections

boolean

Defines whether to allow multiple physical devices to connect to the Hub with this device's credentials.

object

Filter-sets to restrict the topics the device can publish/subscribe to.

has_custom_certificate

boolean

Defines whether the device was assigned a custom certificate. Assigning a custom certificate allows a device to authenticate using that specific certificate without checking the Hub's CA certificate.

created_at

string · date-time

Date at which the device was added. (RFC 3339 format)

updated_at

string · date-time

Date at which the device was last modified. (RFC 3339 format)

region

string

Region of the device.

POST/iot/v1/regions/{region}/devices/{device_id}/disable

curl -X POST \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "https://api.scaleway.com/iot/v1/regions/{region}/devices/{device_id}/disable"

Example Request Body

{}

json

Example Responses

{
  "id": "id",
  "name": "name",
  "description": "description",
  "status": "unknown",
  "hub_id": "hub_id",
  "last_activity_at": "2022-03-22T12:34:56.123456Z",
  "is_connected": true,
  "allow_insecure": true,
  "allow_multiple_connections": true,
  "message_filters": {
    "publish": {
      "policy": "unknown",
      "topics": [
        "string"
      ]
    },
    "subscribe": {
      "policy": "unknown",
      "topics": [
        "string"
      ]
    }
  },
  "has_custom_certificate": true,
  "created_at": "2022-03-22T12:34:56.123456Z",
  "updated_at": "2022-03-22T12:34:56.123456Z",
  "region": "region"
}

json

application/json

Enable a device

POST

https://api.scaleway.com

/iot/v1/regions/{region}/devices/{device_id}/enable

Enable a specific device, specified by its device ID.

Enable a device › path Parameters

region

string · enum · required

The region you want to target

Enum values:

fr-par

device_id

string · required

Device ID.

Enable a device › Request Body

Enable a device › Responses

200

scaleway.iot.v1.Device

id

string

Device ID, also used as MQTT Client ID or username.

name

string

Device name.

description

string

Device description.

status

string · enum

Device status.

Enum values:

unknown

error

enabled

disabled

Default: unknown

hub_id

string

Hub ID.

last_activity_at

string · date-time

Last connection/activity date of a device. (RFC 3339 format)

is_connected

boolean

Defines whether the device is connected to the Hub.

allow_insecure

boolean

Defines whether to allow the device to connect to the Hub without TLS mutual authentication.

allow_multiple_connections

boolean

Defines whether to allow multiple physical devices to connect to the Hub with this device's credentials.

object

Filter-sets to restrict the topics the device can publish/subscribe to.

has_custom_certificate

boolean

Defines whether the device was assigned a custom certificate. Assigning a custom certificate allows a device to authenticate using that specific certificate without checking the Hub's CA certificate.

created_at

string · date-time

Date at which the device was added. (RFC 3339 format)

updated_at

string · date-time

Date at which the device was last modified. (RFC 3339 format)

region

string

Region of the device.

POST/iot/v1/regions/{region}/devices/{device_id}/enable

curl -X POST \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "https://api.scaleway.com/iot/v1/regions/{region}/devices/{device_id}/enable"

Example Request Body

{}

json

Example Responses

{
  "id": "id",
  "name": "name",
  "description": "description",
  "status": "unknown",
  "hub_id": "hub_id",
  "last_activity_at": "2022-03-22T12:34:56.123456Z",
  "is_connected": true,
  "allow_insecure": true,
  "allow_multiple_connections": true,
  "message_filters": {
    "publish": {
      "policy": "unknown",
      "topics": [
        "string"
      ]
    },
    "subscribe": {
      "policy": "unknown",
      "topics": [
        "string"
      ]
    }
  },
  "has_custom_certificate": true,
  "created_at": "2022-03-22T12:34:56.123456Z",
  "updated_at": "2022-03-22T12:34:56.123456Z",
  "region": "region"
}

json

application/json

deprecated

Get a device's metrics

GET

https://api.scaleway.com

/iot/v1/regions/{region}/devices/{device_id}/metrics

Get the metrics of an existing device, specified by its device ID.

Get a device's metrics › path Parameters

region

string · enum · required

The region you want to target

Enum values:

fr-par

device_id

string · required

Device ID.

Get a device's metrics › query Parameters

start_date

string · date-time

Start date used to compute the best scale for the returned metrics. (RFC 3339 format)

Get a device's metrics › Responses

200

scaleway.iot.v1.GetDeviceMetricsResponse

scaleway.std.TimeSeries[]

Metrics for a device over the requested period.

Renew a device certificate

POST

https://api.scaleway.com

/iot/v1/regions/{region}/devices/{device_id}/renew-certificate

Renew the certificate of an existing device, specified by its device ID.

Renew a device certificate › path Parameters

region

string · enum · required

The region you want to target

Enum values:

fr-par

device_id

string · required

Device ID.

Renew a device certificate › Request Body

Renew a device certificate › Responses

200

scaleway.iot.v1.RenewDeviceCertificateResponse

object

Information related to the created device.

object

Device certificate.

POST/iot/v1/regions/{region}/devices/{device_id}/renew-certificate

curl -X POST \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "https://api.scaleway.com/iot/v1/regions/{region}/devices/{device_id}/renew-certificate"

Example Request Body

{}

json

Example Responses

{
  "device": {
    "id": "id",
    "name": "name",
    "description": "description",
    "status": "unknown",
    "hub_id": "hub_id",
    "last_activity_at": "2022-03-22T12:34:56.123456Z",
    "is_connected": true,
    "allow_insecure": true,
    "allow_multiple_connections": true,
    "message_filters": {
      "publish": {
        "policy": "unknown",
        "topics": [
          "string"
        ]
      },
      "subscribe": {
        "policy": "unknown",
        "topics": [
          "string"
        ]
      }
    },
    "has_custom_certificate": true,
    "created_at": "2022-03-22T12:34:56.123456Z",
    "updated_at": "2022-03-22T12:34:56.123456Z",
    "region": "region"
  },
  "certificate": {
    "crt": "crt",
    "key": "key"
  }
}

json

application/json

IoT Hubs IoT Routes