---
title: Migrating from Scaleway IoT Hub API v1beta1
description: This page shows how to migrate to the new IoT Hub API version.
tags: iot-hub iot hub api v1beta1
dates:
  validation: 2025-11-19
---
import Requirements from '@macros/iam/requirements.mdx'


<Requirements />

- [Owner](/iam/concepts/#owner) status or [IAM permissions](/iam/concepts/#permission) allowing you to perform actions in the intended Organization

<Message type="important">
  To ensure that users of the `v1beta1` API have enough time to migrate, this version will remain online until **November 30th 2021**.
</Message>

Here is a list of changes introduced by v1 of the IoT Hub API. Do not expect any major changes, this release is dedicated to cleaning up and improving the API to prepare for new features.

- **Scaleway Projects**: This API version fully supports the new Project system. This means that from now on, IoT Hubs do not belong to an Organization but to a Project. To create an IoT Hub in a project, the Project ID must be passed in the `project_id` field.
> **Note**: The ID of the **default** project is the same as the Organization ID
- **Cleanup**: As Hubs are the main resource, and routes, devices and networks are attached to a Hub, Organization/Project IDs are no longer returned for resources that are not Hubs.
- **Metrics format**: The metrics format has [slightly changed](#metrics-format-change).
- **Device creation**: The returned device certificate and key are now embedded in a JSON object named `certificate`. See [Device creation](#device-creation) for a detailed explanation.
- **Device names**: The device names are now **unique** (inside a hub) and **read only**. If you need to add a description to a device, you can do so via the newly-added field `description`.

## Metrics format change

The `v1beta1` metrics endpoints would follow this format:

```json
{
    "metrics": [
        {
            "name": "<metric name>",
            "values": [
                {
                    "time": "<timestamp>",
                    "value": 1
                }
            ]
        }
    ]
}
```

To have a consistent experience across Scaleway products, a common metrics format has been adopted. The changes are:

- `"values"` were renamed to `"points"`.
- `"time"` has been renamed to `"timestamp"`.
- `"points"`'s `"value"` is now a float number instead of an integer.

```json
{
    "metrics": [
        {
            "name": "<metric name>",
            "points": [
                {
                    "timestamp": "<timestamp>",
                    "value": 2.0
                }
            ]
        }
    ]
}
```

## Device creation

When creating a device, the `v1beta1` used to return the device certificate and key at the root of the response object:

```json
{
    "device_id": "<device id>",
    "crt": "<cert>",
    "key": "<key>"
}
```

To have a consistent experience with device certificates, the certificates are now embedded in a certificate object.

```json
{
    "device_id": "<device id>",
    "certificate": {
        "crt": "<cert>",
        "key": "<key>"
    }
}
```

<Message type="important">
  The certificate object will be removed from the response if the Hub is using a custom Certificate Authority, as we do not possess the keys of such a CA.
</Message>