组织版 Connect

介绍

组织版 Connect 支持多名用户共享设备访问权限。使用 Raspberry Pi Connect 实现。

组织中的设备支持 Connect 的所有功能，包括屏幕共享、远程 Shell 访问和远程更新。

创建首个组织即可自动开始为期四周的免费试用。

创建组织

创建新组织时，请先登录您的 Raspberry Pi Connect 账户，然后点击导航菜单右上角的账户切换图标。

选择新建组织并输入名称。如果您是首次创建组织，将显示开始免费试用；如果您之前已创建过组织，则显示创建组织。点击显示的按钮继续。

组织创建完成后，您的 Connect 账户会自动加入该组织并成为管理员。

如果您的个人账户中已有关联的设备，可以将它们全部转移到刚创建的组织。

要转移设备：

1. 在提示中选择*将它们全部转移到此组织？*链接。

   随即显示转移个人设备页面。

   

   如果您有可转移到新组织的个人设备，系统会在转移前要求您确认：

   

2. 选择个人设备链接查看个人设备，或选择转移 x 台设备（其中"x"为设备数量）确认将计费设备添加到组织账户。

   如果暂不添加设备，可以稍后操作。请参阅转移设备。

管理用户

您必须是管理员才能邀请用户加入、从组织中移除用户或更改用户在组织中的角色。

邀请用户的步骤：

1. 登录您的 Raspberry Pi Connect 账户。

2. 点击导航菜单右上角的账户切换图标（两个相对的箭头），然后从列表中选择您的组织。

3. 选择页面顶部的用户选项卡，然后点击邀请他人。

   

4. 从下拉菜单中选择角色。

   组织成员可选两种角色：

   • 成员：可使用屏幕共享和远程 Shell 远程访问组织内所有设备，但无法部署远程更新或对组织进行任何修改。
   • 管理员：可远程访问组织内所有设备、部署远程更新并修改组织设置。该角色还将接收涉及敏感操作的全局通知邮件，例如新增设备或新的管理 API 访问令牌。

5. 输入您要发送邀请的邮箱地址。

6. 选择发送邀请。

   

   邀请邮件会发送至您在第 5 步提供的邮箱地址。用户可通过邮件中的邀请链接加入，并可使用该邮箱或任何有效的 Raspberry Pi ID 登录。

移除用户的步骤：

1. 登录您的 Raspberry Pi Connect 账户。

2. 点击导航菜单右上角的账户切换图标（两个相对的箭头），然后从列表中选择您的组织。

3. 选择页面顶部的用户选项卡。

   此处会显示组织的所有成员。

4. 在要移除的用户旁边，点击更多选项图标（三个垂直排列的点），然后选择移除...。

   弹出确认窗口。

5. 如果您确认要移除该用户，请选择移除用户。

   该用户会立即从组织中移除，其与贵组织的 shell 与屏幕共享会话会在几分钟内终止。

更改用户角色的步骤：

1. 登录您的 Raspberry Pi Connect 账户。

2. 点击导航菜单右上角的账户切换图标（两个相对的箭头），然后从列表中选择您的组织。

3. 选择页面顶部的用户选项卡。

   此处会显示组织的所有成员。

4. 在要更改角色的用户旁边，点击更多选项图标（三个垂直排列的点），然后选择更改角色...。

5. 从下拉菜单中为该用户选择要分配的角色，然后选择更改角色。

   用户角色已更改，并显示确认页面。

将树莓派设备关联至组织

仅管理员可将设备关联至组织。操作步骤：

• 若设备未关联Connect账户，请参阅 将树莓派设备关联至Connect账户。

• 若设备已关联Connect账户，请参阅 转移设备。

转移设备

您必须是管理员才能在账户间转移设备。操作步骤如下：

1. 点击导航菜单右上角的账户切换图标。

   

2. 切换至当前拥有该设备的账户（个人账户或组织账户）。

3. 选择需要转移的设备。

4. 在设备页面上选择设置。

5. 在危险区域下，选择转移设备…

   

6. 选择目标接收账户。

7. 点击转移。

标记设备

标签帮助您对组织中的设备进行分类和查找。例如，您可以按位置（london、leeds）、环境（production、staging）或功能（point-of-sale、kiosk）对设备打标签。

标签会显示在设备页面和设备列表中设备名称下方。

您必须是管理员才能添加或移除标签。

要为设备添加或移除标签：

1. 从设备列表中选择设备。

2. 在设备页面上选择设置。

   

3. 在常规部分的标签字段中：

   • 要添加标签，请在文本框中输入。您可以从下拉菜单中选择已有标签，或输入新标签名称并选择 创建 选项。
   • 要移除标签，请选择标签旁的 x。

4. 选择更新设备保存更改。

每台设备最多支持 10 个标签。标签名称不得超过 30 个字符，且只能包含小写字母、数字、连字符和下划线。

搜索和筛选设备

设备列表顶部的搜索栏让您可以结合自由文本搜索和结构化筛选查找设备。

要按设备名称或序列号搜索，在搜索栏中输入任意文本。结果会随输入自动更新。

要按特定属性筛选，输入限定符后跟冒号和值。可用的限定符有：

限定符	说明
model:	按树莓派型号筛选（例如 model:5、model:4b）
memory:	按 RAM 大小筛选（例如 memory:4gb、memory:512mb）
os:	按操作系统筛选（例如 os:raspios-13）
tag:	按标签筛选（例如 tag:kiosk、tag:production）

备注

model:、memory: 和 os: 限定符仅能查找运行 Connect 客户端 2.9.0 及更高版本的设备。要更新设备上的 Connect，请参阅 更新。

您可以在一次查询中组合多个筛选和自由文本。例如，model:5 tag:production dashboard 可查找名称中带有 "dashboard"、标签为 production 的树莓派 5 设备。

当您开始在搜索栏中输入时，下拉菜单会建议可用的限定符和值。从下拉菜单中选择一个限定符可查看其可用值，然后选择一个值将其作为筛选添加。已应用的筛选会显示在搜索栏中。

要移除筛选，选择它旁边的 x 或按 Backspace。

多次使用 tag: 限定符可查找同时具有 所有 指定标签的设备。例如，tag:production tag:kiosk 仅返回同时具有 production 和 kiosk 标签的设备。

提示

在列表中任何设备上选择标签可快速将其添加为筛选。

部署远程更新

您可以使用 Raspberry Pi Connect 的远程更新功能向组织中的设备推送更新。向组织设备部署的方式与向个人设备部署大致相同，但有以下区别：

• 组织会维护一个工件库，您可以多次部署其中的工件。
• 除了上传工件，您还可以自行托管工件，这样工件在您等待设备上线期间不会过期。
• 您可以使用管理 API 管理工件和部署。

备注

仅管理员可以部署远程更新并管理更新工件。

首先，请按脚本工件或 A/B 启动更新中所述构建更新工件。

然后选择将其提供给 Raspberry Pi Connect 的方式：

• 上传工件：Connect 会为您托管该文件。上传大小限制为 2 GB，并在上传两小时后过期。设备若未在此时间内接收部署，将无法收到该工件。
• 自行托管工件：您将文件托管在接收设备可以下载的位置，并提供其位置，具体说明见托管更新工件。自行托管的工件不会过期，因此对于可能离线超过两小时的设备，或者需要在一段时间内向多台设备部署同一工件的情况，请选择此方式。

托管更新工件

当您自行托管工件时，Raspberry Pi Connect 不会存储该文件。相反，您向 Connect 提供其位置，Connect 会将该位置传递给接收设备，以便设备直接下载文件。

您可以将工件托管在接收设备能够访问的任何位置：您自己的 Web 服务器、S3 存储桶、FTP 或 SFTP 服务器，或者使用 file:// URI 指向接收设备本身上的路径。远程更新支持 HTTP、HTTPS、FTP、SFTP 和 File URI。

该位置必须可供接收设备访问，但无需对 Raspberry Pi Connect 服务器或整个互联网开放。从与接收设备位于同一本地网络的另一台计算机上提供工件是一种很好的做法。

以下是一个示例 URI：http://192.168.0.1:8080/path/to/app.update.tar.zst

它包含以下必需信息：

• 主机 IP：192.168.0.1
• 端口：8080
• 路径：/path/to/app.update.tar.zst

您还需要工件的 SHA-256 校验和，Connect 会将其传递给设备，以便设备检查工件在传输过程中是否损坏或被篡改。otamaker 在构建脚本工件时会输出校验和；否则，请使用 sha256sum 计算。

记下 URI 和校验和；部署工件时这两者都需要。

示例：从树莓派提供工件

以下示例从与接收设备位于同一网络的树莓派主机上提供更新工件。

1. 在主机上运行 HTTP 服务器，相应更改工件目录：

   python -m http.server 8080 --directory ./work/image-myapp

2. 计算更新文件的 SHA-256 校验和，然后记下该校验和：

   sha256sum ./work/image-myapp/myapp-update.tar.zst

3. 查找主机在本地网络上的 IP 地址，然后记下该 IP 地址。您需要用它来构建工件的 URI：

   hostname -I

管理工件库

组织会维护一个工件库，列在 远程更新 选项卡下。您在部署时创建的工件也会添加到该库中。

要预先将工件添加到库中，请前往 远程更新 选项卡，选择 新建，然后选择以下方式之一：

• 上传工件：输入名称并选择文件，具体说明见上传工件，然后选择 Upload artefact。
• 自行托管工件：输入名称、URI 和 SHA-256 校验和，然后选择 Save artefact。

工件库还会显示每个已上传工件的 Expires（过期时间），以及过期后的 Expired（已过期）状态。已过期的工件仍保留在库中，以便您查看曾经部署过什么，但无法再次部署。要再次部署同一文件，请重新上传。

备注

工件一旦被部署或尝试部署后便无法删除。这是为了在您的账户遭到入侵时提供可追溯性。

部署工件

要部署工件，请前往 设备 选项卡，然后在接收设备旁选择 部署。部署 按钮仅对已启用远程更新的设备显示。

然后，在 新建部署 界面上，选择以下选项之一：

• 使用现有工件：从库中选择一个工件，然后选择 下一步。列表中的每个工件都会显示其名称、校验和的前几个字符、其 URI 或文件名与大小；对于已上传的工件，还会显示距离过期还有多久。已过期的工件不会出现在列表中。
• 上传工件：输入名称并选择文件，具体说明见上传工件，然后选择 下一步。
• 自行托管工件：输入名称、URI 和 SHA-256 校验和，然后选择 下一步。

在 第 2 步：检查并部署 中，确认工件的详细信息，然后选择 部署。对于上传的工件，此步骤还会显示文件的过期时间；只有当接收设备在此之前上线并开始部署时，部署才会成功。

请按照监控部署中所述跟踪部署进度。

您也可以使用管理 API 自动管理更新工件和部署。

设置订阅服务

组织版Connect订阅将在四周试用期结束后自动生效，此后按月延后计费。

仅管理员可设置订阅。操作步骤：

1. 点击页面顶部标签栏下方试用横幅中的设置计费.
2. 输入用于接收账单通知（如发票）的邮箱地址.
3. 填写支付方式信息并提交
   • 若试用期未结束，按钮显示为开始试用 试用期将延续，之后按月计费。
   • 若试用期已结束，按钮显示为支付并订阅。此操作将启动月度订阅。

免费试用结束后，若未设置订阅，您将无法远程访问组织内的设备。

查看审计日志

审计日志按时间顺序显示过去90天内的所有活动，最新事件优先显示。事件包括设备变更、组织成员变更、API访问令牌变更以及远程访问会话等。超过90天的事件将自动删除。

仅管理员可查看组织过去90天的活动记录。要查看审计日志，请打开页面顶部的审计日志选项卡。

列表中的每个事件包含以下信息：

• 时间戳： 事件发生的时间。
• 来源：事件发生于仪表板还是通过API触发。
• 操作：具体操作（例如API访问令牌创建）及相关细节。
• 对象：操作涉及的对象，如特定设备、组织或访问令牌。
• 执行者：执行事件的用户，包含事件发生所在国家/地区。

您可按操作类型（如远程shell会话启动）筛选事件。筛选列表时，请点击列表左上角筛选器旁的操作下拉菜单。

点击列表右上角的下载CSV即可下载事件列表的CSV格式文件。

修改组织设置

组织管理员可在页面顶部的设置选项卡中配置以下内容。

重命名组织

若需更改组织名称，请在常规部分输入新名称。此操作不会影响您的设备或组织成员。

要求双因素认证

您可以要求组织的所有成员在其 Raspberry Pi ID 上启用双因素认证（2FA）。这能为贵组织设备的访问增加一层保护，防止成员账户被泄露后被用于访问组织设备。

启用 2FA 要求的步骤：

1. 登录 Raspberry Pi Connect。

2. 在右上角的账户切换图标中选择您的组织账户。

3. 选择设置选项卡，然后选择要求双因素认证。

   页面会显示通知，确认组织设置已成功更新。

这会启动 14 天的宽限期。在宽限期内，我们会向尚未启用 2FA 的组织成员显示横幅。

宽限期结束后，仍未启用 2FA 的成员将被阻止访问贵组织。在他们启用 Raspberry Pi ID 的 2FA 之前，他们将无法访问组织的设备或其他资源。

禁用 2FA 要求的步骤：

1. 登录 Raspberry Pi Connect。

2. 在右上角的账户切换图标中选择您的组织账户。

3. 选择设置选项卡，然后选择停止要求双因素认证。

   页面会显示通知，确认组织设置已成功更新。

备注

禁用后再重新启用 2FA 要求会重置 14 天宽限期。

创建授权密钥

若需通过 Connect 自动关联设备（无需网页界面）进行操作，请创建授权密钥。在授权密钥区域选择新建，填写描述及有效期（1至90天）。

新授权密钥将显示。点击其旁的剪贴板图标即可复制。请立即复制此密钥，后续将无法再次查看。

重要提示：授权密钥仅显示一次。请立即复制，后续将无法再次查看。

创建管理API访问令牌

若需自动生成授权密钥（无需网页界面）以 连接设备至Connect，可创建 Connect for Organisations管理API 的API访问令牌。在API访问令牌区域选择新建，并输入令牌描述。

警告

管理 API 访问令牌相当于您组织的管理员用户名和密码。它可以管理组织中的每台设备、每个授权密钥和每个设备身份。请将其保存在调用管理 API 的机器上（如部署配置工作站或 CI 系统）；切勿将其嵌入树莓派操作系统镜像或复制到任何设备上。要对设备本身进行身份验证，请使用设备身份或授权密钥为每台设备生成凭证并分发。

新访问令牌将显示。点击其旁的剪贴板图标进行复制。请立即复制此令牌，后续将无法再次查看。

重要提示：访问令牌仅显示一次。请立即复制，后续将无法再次查看。

管理API

管理API支持您无需Connect网页界面即可自动管理组织。向管理API发送请求时，必须使用有效的管理API访问令牌进行身份验证。基础URL为 https://api.connect.raspberrypi.com。

速率限制

每个管理 API 访问令牌每小时最多可发起 5,000 次请求。该限制按固定的一小时窗口计量：计数器在每小时开始时重置，与您在该小时内首次发起请求的时间无关。

每个经过身份验证的请求响应都包含以下标头，便于您跟踪用量：

• X-Rate-Limit-Limit：每小时允许的最大请求数。
• X-Rate-Limit-Remaining：当前小时剩余的请求数。
• X-Rate-Limit-Reset：距离当前小时结束、计数器重置的秒数。

例如：

HTTP/2 200
Content-Type: application/json; charset=utf-8
X-Rate-Limit-Limit: 5000
X-Rate-Limit-Remaining: 4999
X-Rate-Limit-Reset: 3600

如果超出限制，您将收到带有相同标头的 429 Too Many Requests 响应。请等待 X-Rate-Limit-Reset 中给出的秒数后再重试。例如：

HTTP/2 429
X-Rate-Limit-Limit: 5000
X-Rate-Limit-Remaining: 0
X-Rate-Limit-Reset: 1800

Throttled

备注

使用无效访问令牌发起的请求仍会计入该令牌的限制，但响应中不会包含速率限制标头。

创建设备身份

设备身份（Device identities）让您无需交互式登录即可预先将树莓派设备认证到组织。与授权密钥不同，设备身份可多次使用，并依赖存储在设备一次性可编程内存中的私钥。

创建设备身份是免费的。您仅在设备首次通过认证连接到组织的 Connect 账户时开始计费，这使得设备身份非常适合在部署前预配置 Connect 的组织场景。

请求必须包含 X-Connect-Identity-Signature 标头。要生成该标头，请构造一个以换行分隔的有效载荷，按顺序包含：

• HTTP 请求方法（例如 POST）
• 完整的请求 URL
• Authorization: <值>
• Content-Type: <值>
• Accept: <值>（如果您的 HTTP 客户端会发送此标头）
• HTTP 请求正文的 SHA256 十六进制摘要（下面 POST 所示的 JSON 请求正文）

使用设备的私钥，以 ECDSA with SHA256 对此有效载荷进行签名，然后进行 Base64 编码。

例如，一个注册设备身份的请求会产生以下有效载荷：

POST
https://api.connect.raspberrypi.com/organisation/device-identities
Authorization: Bearer rporg_accesstokenhere
Content-Type: application/json
Accept: */*
<HTTP 请求正文的 SHA256 十六进制摘要>

在设备上，使用 rpi-fw-crypto 对有效载荷进行签名。例如，将有效载荷写入 payload.txt 后：

rpi-fw-crypto sign --in payload.txt --key-id 1 --alg ec | base64 -w 0

输出即为 X-Connect-Identity-Signature 标头的值。

要为您的组织创建设备身份，请使用 管理 API 访问令牌 发起以下 HTTP 请求。

请替换以下代码中的参数：

• rporg_accesstokenhere：您的管理 API 访问令牌。
• signaturehere：此请求的 X-Connect-Identity-Signature 值。
• -----BEGIN PUBLIC KEY-----...：设备的 PEM 编码公钥。
• my-device-identity：设备身份的描述，可在组织审计日志中看到。
• pi5-001：交换身份时分配给设备的名称（可选，默认为设备的主机名）。
• production、kiosk：（可选）交换身份时应用到设备的标签。每个标签只能包含小写字母、数字、连字符和下划线，最多 30 个字符。每个设备身份最多可应用 10 个标签。

POST /organisation/device-identities HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere
Content-Type: application/json
X-Connect-Identity-Signature: signaturehere

{
    "public_key": "-----BEGIN PUBLIC KEY-----...",
    "description": "my-device-identity",
    "device_name": "pi5-001",
    "tags": ["production", "kiosk"]
}

curl 示例：

curl --header 'Authorization: Bearer rporg_accesstokenhere' --header 'X-Connect-Identity-Signature: signaturehere' --header 'Content-Type: application/json' --data '{"public_key":"-----BEGIN PUBLIC KEY-----...","description":"my-device-identity","device_name":"pi5-001","tags":["production","kiosk"]}' https://api.connect.raspberrypi.com/organisation/device-identities

若成功，您会收到 201 Created 响应，其中包含 JSON 格式的设备身份。例如：

HTTP/2 201
Content-Type: application/json; charset=utf-8

{
    "id": "096ce472-2cbd-412a-8295-6c03a1a07ba4",
    "description": "my-device-identity",
    "device_name": "pi5-001",
    "tags": ["production", "kiosk"],
    "created_at": "2026-02-25T16:09:52Z",
    "public_key": "-----BEGIN PUBLIC KEY-----..."
}

响应包含以下字段：

• id：设备身份的唯一标识符。
• description：用于创建设备身份的描述。
• device_name：交换身份时分配给设备的名称。
• tags：交换身份时应用到设备的标签。
• created_at：创建设备身份的日期和时间（ISO 8601 格式）。
• public_key：设备身份对应的 PEM 编码公钥。

否则，您会收到以下响应之一：

响应	说明	示例
401 Unauthorized	管理 API 访问令牌无效。
422 Unprocessable Content	设备身份无法创建。	{"message":"Validation failed: Public key is invalid"}

列出设备身份

如需列出组织中的所有设备身份，请使用 管理 API 访问令牌 发起以下 HTTP 请求。

请替换下方代码中的参数：

• rporg_accesstokenhere：您的管理 API 访问令牌。

HTTP

GET /organisation/device-identities HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere

curl

curl --header 'Authorization: Bearer rporg_accesstokenhere' https://api.connect.raspberrypi.com/organisation/device-identities

若成功，将返回 200 OK 响应，其中包含最多 100 个按描述字母顺序排列的组织设备身份，采用 JSON 格式。例如：

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

{
    "device_identities": [
        {
            "id": "096ce472-2cbd-412a-8295-6c03a1a07ba4",
            "description": "my-device-identity",
            "device_name": "pi5-001",
            "tags": [],
            "created_at": "2026-02-25T16:09:52Z",
            "public_key": "-----BEGIN PUBLIC KEY-----..."
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 100,
        "total_count": 1,
        "total_pages": 1
    }
}

响应包含以下字段：

device_identities：组织中的设备身份列表（每页最多 100 个）。 meta：分页详情。

device_identities 列表中的每个项目包含以下字段：

id：设备身份的唯一标识符。 description：创建设备身份时使用的描述。 device_name：交换身份时分配给设备的名称。 tags：交换身份时应用到设备的标签。 created_at：创建设备身份的日期和时间（ISO 8601 格式）。 public_key：设备身份对应的 PEM 编码公钥。

meta 对象包含以下字段：

page：响应的当前页码。 per_page：每页的设备身份数量（最多 100）。 total_count：组织中的设备身份总数。 total_pages：组织设备身份的总页数。

若管理 API 访问令牌无效，将返回 401 Unauthorized 响应。

page 和 per_page 查询参数的用法与列出设备相同。

显示设备身份

如需显示组织中的单个设备身份，请使用 管理 API 访问令牌 发起以下 HTTP 请求。

请替换下方代码中的参数：

• rporg_accesstokenhere：您的管理 API 访问令牌。
• device-identity-id：设备身份的唯一标识符。

HTTP

GET /organisation/device-identities/device-identity-id HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere

curl

curl --header 'Authorization: Bearer rporg_accesstokenhere' https://api.connect.raspberrypi.com/organisation/device-identities/device-identity-id

若成功，将返回 200 OK 响应，其中包含设备身份的详细信息，采用 JSON 格式。例如：

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

{
    "id": "096ce472-2cbd-412a-8295-6c03a1a07ba4",
    "description": "my-device-identity",
    "device_name": "pi5-001",
    "tags": [],
    "created_at": "2026-02-25T16:09:52Z",
    "public_key": "-----BEGIN PUBLIC KEY-----..."
}

若管理 API 访问令牌无效，将返回 401 Unauthorized 响应。

若在组织中未找到该设备身份，将返回 404 Not Found 响应。

更新设备身份

如需更新组织中的现有设备身份，请使用 管理 API 访问令牌 发起以下 HTTP 请求。

请替换下方代码中的参数：

• rporg_accesstokenhere：您的管理 API 访问令牌。
• device-identity-id：设备身份的唯一标识符。
• my-renamed-device-identity：设备身份的新描述。
• pi5-001：交换身份时分配给设备的新名称（可选）。
• production、kiosk：交换身份时应用到设备的标签（可选）。

JSON

PATCH /organisation/device-identities/device-identity-id HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere
Content-Type: application/json

{
    "description": "my-renamed-device-identity",
    "device_name": "pi5-001",
    "tags": ["production", "kiosk"]
}

curl

curl --request PATCH --header 'Authorization: Bearer rporg_accesstokenhere' --header 'Content-Type: application/json' --data '{"description":"my-renamed-device-identity","device_name":"pi5-001","tags":["production","kiosk"]}' https://api.connect.raspberrypi.com/organisation/device-identities/device-identity-id

若成功，将返回 200 OK 响应，其中包含更新后的设备身份，采用 JSON 格式：

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

{
    "id": "096ce472-2cbd-412a-8295-6c03a1a07ba4",
    "description": "my-renamed-device-identity",
    "device_name": "pi5-001",
    "tags": ["production", "kiosk"],
    "created_at": "2026-02-25T16:09:52Z",
    "public_key": "-----BEGIN PUBLIC KEY-----..."
}

备注

设备身份一旦被交换为设备后，只能更新 description 字段。请求正文中的任何 device_name 或 tags 值将被忽略，因为这些字段仅在身份首次交换时应用。

若管理 API 访问令牌无效，将返回 401 Unauthorized 响应。

若在组织中未找到该设备身份，将返回 404 Not Found 响应。

若设备身份无法更新，将返回 422 Unprocessable Content 响应，其中包含无法更新的原因：

{"message":"Validation failed: Description can't be blank"}

删除设备身份

如需删除组织中的设备身份，请使用 管理 API 访问令牌 发起以下 HTTP 请求。

请替换下方代码中的参数：

• rporg_accesstokenhere：您的管理 API 访问令牌。
• device-identity-id：设备身份的唯一标识符。

HTTP

DELETE /organisation/device-identities/device-identity-id HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere

curl

curl --request DELETE --header 'Authorization: Bearer rporg_accesstokenhere' https://api.connect.raspberrypi.com/organisation/device-identities/device-identity-id

如果设备身份已被交换为设备，关联的设备也将被删除并从 Raspberry Pi Connect 中退出。

若成功，将返回 200 OK 响应，其中包含已删除设备身份的详细信息，采用 JSON 格式。例如：

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

{
    "id": "096ce472-2cbd-412a-8295-6c03a1a07ba4",
    "description": "my-device-identity",
    "device_name": "pi5-001",
    "tags": [],
    "created_at": "2026-02-25T16:09:52Z",
    "public_key": "-----BEGIN PUBLIC KEY-----..."
}

若管理 API 访问令牌无效，将返回 401 Unauthorized 响应。

若在组织中未找到该设备身份，将返回 404 Not Found 响应。

列出工件

如需列出组织中的所有远程更新工件，请使用 管理 API 访问令牌 发起以下 HTTP 请求。

请替换下方代码中的参数：

• rporg_accesstokenhere：您的管理 API 访问令牌。

HTTP

GET /organisation/artefacts HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere

curl

curl --header 'Authorization: Bearer rporg_accesstokenhere' https://api.connect.raspberrypi.com/organisation/artefacts

若成功，将返回 200 OK 响应，其中包含最多 100 个组织工件，采用 JSON 格式，按名称字母顺序排序，再按创建时间排序（最早的在前）。例如：

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

{
    "artefacts": [
        {
            "id": "ee92e7e6-2c2c-4e7d-9d80-2cce8a6c7e8a",
            "name": "kiosk-v1.0",
            "type": "uri",
            "uri": "https://example.com/kiosk-v1.0.tar.zst",
            "checksum": "d39fc02ad7878db7f6803f54dfce89346a763a603cb8e62221ba893fee9c5cc6",
            "expires_at": null,
            "created_at": "2026-02-25T16:09:52Z"
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 100,
        "total_count": 1,
        "total_pages": 1
    }
}

如需按名称筛选返回的工件，请在查询字符串中使用 name 参数。这会执行大小写不敏感的前缀匹配：

HTTP

GET /organisation/artefacts?name=kiosk HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere

curl

curl --header 'Authorization: Bearer rporg_accesstokenhere' --get --data-urlencode 'name=kiosk' https://api.connect.raspberrypi.com/organisation/artefacts

page 和 per_page 查询参数的用法与列出设备相同，且可与 name 参数组合使用，方便对筛选结果进行分页。

每个工件包含以下字段：

• id：工件的唯一标识符。
• name：工件的名称。名称在组织内不必唯一。
• type：工件的提供方式：uri 表示您自行托管的工件，file 表示上传到 Connect 的工件。
• uri：设备下载工件的位置。对于已上传的工件，这是指向已上传文件的链接；一旦 Connect 删除该文件，则为 null。
• checksum：工件的十六进制 SHA-256 校验和。
• expires_at：已上传工件过期且无法再部署的日期和时间（ISO 8601 格式）；对于您自行托管的工件，则为 null。
• created_at：工件的创建日期和时间（ISO 8601 格式）。

若管理 API 访问令牌无效，将返回 401 Unauthorized 响应。

显示工件

如需显示组织中的单个远程更新工件，请使用 管理 API 访问令牌 发起以下 HTTP 请求。

请替换下方代码中的参数：

• rporg_accesstokenhere：您的管理 API 访问令牌。
• artefact-id：工件的唯一标识符。

HTTP

GET /organisation/artefacts/artefact-id HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere

curl

curl --header 'Authorization: Bearer rporg_accesstokenhere' https://api.connect.raspberrypi.com/organisation/artefacts/artefact-id

若成功，将返回 200 OK 响应，其中包含该工件的详细信息，采用 JSON 格式。例如：

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

{
    "id": "ee92e7e6-2c2c-4e7d-9d80-2cce8a6c7e8a",
    "name": "kiosk-v1.0",
    "type": "uri",
    "uri": "https://example.com/kiosk-v1.0.tar.zst",
    "checksum": "d39fc02ad7878db7f6803f54dfce89346a763a603cb8e62221ba893fee9c5cc6",
    "expires_at": null,
    "created_at": "2026-02-25T16:09:52Z"
}

否则，您将收到以下响应之一：

响应	说明
401 Unauthorized	管理 API 访问令牌无效。
404 Not Found	组织中未找到给定的工件 ID。

创建工件

如需为组织创建远程更新工件，请使用 管理 API 访问令牌 发起以下 HTTP 请求。

备注

管理 API 只能创建您自行托管的工件。要上传工件，请使用远程更新选项卡。

请替换下方代码中的参数：

• rporg_accesstokenhere：您的管理 API 访问令牌。
• kiosk-v1.0：工件的名称。名称在组织内不必唯一。
• https://example.com/kiosk-v1.0.tar.zst：设备下载工件的 URI。
• d39fc02ad7878db7f6803f54dfce89346a763a603cb8e62221ba893fee9c5cc6：工件的十六进制 SHA-256 校验和。

JSON

POST /organisation/artefacts HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere
Content-Type: application/json

{
    "name": "kiosk-v1.0",
    "uri": "https://example.com/kiosk-v1.0.tar.zst",
    "checksum": "d39fc02ad7878db7f6803f54dfce89346a763a603cb8e62221ba893fee9c5cc6"
}

curl

curl --header 'Authorization: Bearer rporg_accesstokenhere' --data-urlencode 'name=kiosk-v1.0' --data-urlencode 'uri=https://example.com/kiosk-v1.0.tar.zst' --data-urlencode 'checksum=d39fc02ad7878db7f6803f54dfce89346a763a603cb8e62221ba893fee9c5cc6' https://api.connect.raspberrypi.com/organisation/artefacts

若成功，将返回 201 Created 响应，其中包含工件的详细信息，采用 JSON 格式。例如：

HTTP/2 201
Content-Type: application/json; charset=utf-8

{
    "id": "ee92e7e6-2c2c-4e7d-9d80-2cce8a6c7e8a",
    "name": "kiosk-v1.0",
    "uri": "https://example.com/kiosk-v1.0.tar.zst",
    "checksum": "d39fc02ad7878db7f6803f54dfce89346a763a603cb8e62221ba893fee9c5cc6"
}

若管理 API 访问令牌无效，将返回 401 Unauthorized 响应。

若工件无法创建，将返回 422 Unprocessable Content 响应，其中包含无法创建的原因：

HTTP/2 422
Content-Type: application/json; charset=utf-8

{"message":"Validation failed: Name can't be blank"}

删除工件

如需删除组织中的工件，请使用 管理 API 访问令牌 发起以下 HTTP 请求。

请替换下方代码中的参数：

• rporg_accesstokenhere：您的管理 API 访问令牌。
• artefact-id：工件的 id（由创建工件返回）。

HTTP

DELETE /organisation/artefacts/artefact-id HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere

curl

curl --request DELETE --header 'Authorization: Bearer rporg_accesstokenhere' https://api.connect.raspberrypi.com/organisation/artefacts/artefact-id

若成功，将返回 200 OK 响应，其中包含已删除工件的详细信息，采用 JSON 格式。例如：

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

{
    "id": "ee92e7e6-2c2c-4e7d-9d80-2cce8a6c7e8a",
    "name": "kiosk-v1.0",
    "type": "uri",
    "uri": "https://example.com/kiosk-v1.0.tar.zst",
    "checksum": "d39fc02ad7878db7f6803f54dfce89346a763a603cb8e62221ba893fee9c5cc6",
    "expires_at": null,
    "created_at": "2026-02-25T16:09:52Z"
}

若管理 API 访问令牌无效，将返回 401 Unauthorized 响应。

若在组织中未找到给定的工件 ID，将返回 404 Not Found 响应。

若该工件已被部署到设备，将返回 422 Unprocessable Content 响应，其中包含无法删除的原因：

HTTP/2 422
Content-Type: application/json; charset=utf-8

{"message":"Cannot delete artefacts that have been deployed"}

列出部署

如需列出组织中某设备的远程更新部署记录，请使用 管理 API 访问令牌 发起以下 HTTP 请求。

请替换下方代码中的参数：

• rporg_accesstokenhere：您的管理 API 访问令牌。
• device-id：设备的唯一标识符。

HTTP

GET /organisation/devices/device-id/deployments HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere

curl

curl --header 'Authorization: Bearer rporg_accesstokenhere' https://api.connect.raspberrypi.com/organisation/devices/device-id/deployments

若成功，将返回 200 OK 响应，其中包含最多 100 个设备的部署记录，按最新优先排序，采用 JSON 格式。例如：

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

{
    "deployments": [
        {
            "id": "fdf45c44-2c0e-4f12-9b04-3a6a1c0d3b8d",
            "state": "failed",
            "state_reason": "Checksum mismatch",
            "device_id": "69739b44-ebb2-468e-9e24-08126dec4925",
            "artefact_id": "ee92e7e6-2c2c-4e7d-9d80-2cce8a6c7e8a",
            "created_at": "2026-02-25T16:09:52Z",
            "updated_at": "2026-02-25T16:10:30Z"
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 100,
        "total_count": 1,
        "total_pages": 1
    }
}

每个部署的 state 为 queued、in_progress、succeeded、failed、cancelled 或 invalidated 之一。对于 failed 的部署，state_reason 包含部署失败原因的可读说明（例如校验和不匹配或被更新的部署取代）；对于其他状态，该值为 null。

如需按状态筛选返回的部署，请在查询字符串中使用 state 参数，值为上述状态之一。为向后兼容，state=pending 会返回 queued 的部署：

HTTP

GET /organisation/devices/device-id/deployments?state=queued HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere

curl

curl --header 'Authorization: Bearer rporg_accesstokenhere' 'https://api.connect.raspberrypi.com/organisation/devices/device-id/deployments?state=queued'

page 和 per_page 查询参数的用法与列出设备相同。

否则，您会收到以下响应之一：

响应	说明	示例
400 Bad Request	state 参数不是可识别的状态值。	{"message":"Unknown state \"exploded\""}
401 Unauthorized	管理 API 访问令牌无效。
404 Not Found	在组织中未找到给定的设备 ID。

显示部署

如需显示组织中的单个部署，请使用 管理 API 访问令牌 发起以下 HTTP 请求。

请替换下方代码中的参数：

• rporg_accesstokenhere：您的管理 API 访问令牌。
• deployment-id：部署的唯一标识符。

HTTP

GET /organisation/deployments/deployment-id HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere

curl

curl --header 'Authorization: Bearer rporg_accesstokenhere' https://api.connect.raspberrypi.com/organisation/deployments/deployment-id

若成功，将返回 200 OK 响应，其中包含部署的详细信息，采用 JSON 格式。例如：

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

{
    "id": "fdf45c44-2c0e-4f12-9b04-3a6a1c0d3b8d",
    "state": "succeeded",
    "state_reason": null,
    "device_id": "69739b44-ebb2-468e-9e24-08126dec4925",
    "artefact_id": "ee92e7e6-2c2c-4e7d-9d80-2cce8a6c7e8a",
    "created_at": "2026-02-25T16:09:52Z",
    "updated_at": "2026-02-25T16:10:30Z"
}

若管理 API 访问令牌无效，将返回 401 Unauthorized 响应。

若在组织中未找到该部署，将返回 404 Not Found 响应。

创建部署

如需将工件部署到设备，请使用 管理 API 访问令牌 发起以下 HTTP 请求。新部署将取代该设备上已排队的任何部署。

请替换下方代码中的参数：

• rporg_accesstokenhere：您的管理 API 访问令牌。
• device-id：接收设备的唯一标识符。
• artefact-id：工件的 id（由创建工件返回）。

JSON

POST /organisation/devices/device-id/deployments HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere
Content-Type: application/json

{
    "artefact_id": "artefact-id"
}

curl

curl --header 'Authorization: Bearer rporg_accesstokenhere' --data-urlencode 'artefact_id=artefact-id' https://api.connect.raspberrypi.com/organisation/devices/device-id/deployments

若成功，将返回 201 Created 响应，其中包含部署的详细信息，采用 JSON 格式。例如：

HTTP/2 201
Content-Type: application/json; charset=utf-8

{
    "id": "fdf45c44-2c0e-4f12-9b04-3a6a1c0d3b8d",
    "state": "queued",
    "state_reason": null,
    "device_id": "69739b44-ebb2-468e-9e24-08126dec4925",
    "artefact_id": "ee92e7e6-2c2c-4e7d-9d80-2cce8a6c7e8a",
    "created_at": "2026-02-25T16:09:52Z",
    "updated_at": "2026-02-25T16:09:52Z"
}

若缺少 artefact_id，将返回 400 Bad Request 响应。

若管理 API 访问令牌无效，将返回 401 Unauthorized 响应。

若在组织中未找到该设备或工件，或工件已过期，将返回 404 Not Found 响应。

若组织的免费试用已结束且尚未设置计费，将返回 403 Forbidden 响应：

HTTP/2 403
Content-Type: application/json; charset=utf-8

{"message":"Deployments are blocked until billing has been set up"}

取消部署

如需取消已排队的部署，请使用 管理 API 访问令牌 发起以下 HTTP 请求。

请替换下方代码中的参数：

• rporg_accesstokenhere：您的管理 API 访问令牌。
• deployment-id：部署的唯一标识符。

HTTP

PUT /organisation/deployments/deployment-id/cancel HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere

curl

curl --request PUT --header 'Authorization: Bearer rporg_accesstokenhere' https://api.connect.raspberrypi.com/organisation/deployments/deployment-id/cancel

若成功，将返回 200 OK 响应，其中包含更新后的部署详细信息，采用 JSON 格式：

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

{
    "id": "fdf45c44-2c0e-4f12-9b04-3a6a1c0d3b8d",
    "state": "cancelled",
    "state_reason": null,
    "device_id": "69739b44-ebb2-468e-9e24-08126dec4925",
    "artefact_id": "ee92e7e6-2c2c-4e7d-9d80-2cce8a6c7e8a",
    "created_at": "2026-02-25T16:09:52Z",
    "updated_at": "2026-02-25T16:10:30Z"
}

若管理 API 访问令牌无效，将返回 401 Unauthorized 响应。

若在组织中未找到该部署，将返回 404 Not Found 响应。

若部署无法取消（因为已被取消、已成功或已失败），将返回 422 Unprocessable Content 响应，其中包含无法取消的原因：

HTTP/2 422
Content-Type: application/json; charset=utf-8

{"message":"Cannot cancel deployment in state \"succeeded\""}

创建授权密钥

若需自动生成 通过Connect连接设备 的授权密钥，请使用 管理API访问令牌 发起以下HTTP请求。

请替换下方代码中的参数：

• rporg_accesstokenhere：您的管理API访问令牌。
• my-auth-key：授权密钥描述。
• 1：授权密钥有效期天数，范围 1 到 90（可选，默认1天）。
• pi5-001：使用此密钥添加设备时使用的名称（可选，默认为设备的主机名）。
• production、kiosk：交换授权密钥时应用到设备的标签（可选）。每个标签只能包含小写字母、数字、连字符和下划线，最多 30 个字符。每个授权密钥最多可应用 10 个标签。

JSON

POST /organisation/auth-keys HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere
Content-Type: application/json

{
    "description": "my-auth-key",
    "ttl_days": 1,
    "device_name": "pi5-001",
    "tags": ["production", "kiosk"]
}

HTTP

HTTP请求：

POST /organisation/auth-keys HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere
Content-Type: application/x-www-form-urlencoded

description=my-auth-key&ttl_days=1&device_name=pi5-001&tags[]=production&tags[]=kiosk

curl

curl --header 'Authorization: Bearer rporg_accesstokenhere' --data-urlencode 'description=my-auth-key' --data-urlencode 'ttl_days=1' --data-urlencode 'device_name=pi5-001' --data-urlencode 'tags[]=production' --data-urlencode 'tags[]=kiosk' https://api.connect.raspberrypi.com/organisation/auth-keys

若成功，将返回201 Created响应，其中包含JSON格式的授权密钥。例如：

HTTP/2 201
Content-Type: application/json; charset=utf-8

{
    "id": "12345",
    "description": "my-auth-key",
    "device_name": "pi5-001",
    "tags": ["production", "kiosk"],
    "secret": "rpoak_123456",
    "expires_at": "2025-01-01T00:00:30Z",
    "exchanged_at": null,
    "created_at": "2024-12-31T00:00:30Z"
}

响应包含以下字段：

• id：授权密钥的唯一标识符。
• description：创建授权密钥时使用的描述信息。
• device_name：交换授权密钥时分配给设备的名称。
• tags：交换授权密钥时应用到设备的标签。
• secret：以 rpoak_ 为前缀的随机令牌。
• expires_at：密钥过期日期与时间（ISO 8601 格式）。
• exchanged_at：授权密钥交换以关联设备的日期和时间（ISO 8601 格式），如尚未交换则为 null。
• created_at：创建授权密钥的日期和时间（ISO 8601 格式）。

在过期前可使用 secret 进行 设备与Connect的关联。

若管理 API 访问令牌无效，将返回 401 Unauthorized 响应。

若授权密钥创建失败，将返回 422 Unprocessable Content 响应。

{"message":"Validation failed: Description can't be blank"}

提示

您也可手动在组织的设置页面创建授权密钥。

列出授权密钥

如需列出组织中的所有授权密钥，请使用 管理 API 访问令牌 发起以下 HTTP 请求。

请替换下方代码中的参数：

• rporg_accesstokenhere：您的管理 API 访问令牌。

HTTP

GET /organisation/auth-keys HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere

curl

curl --header 'Authorization: Bearer rporg_accesstokenhere' https://api.connect.raspberrypi.com/organisation/auth-keys

若成功，将返回 200 OK 响应，其中包含最多 100 个组织的授权密钥，采用 JSON 格式。排序规则为：可用密钥优先，其次为已过期密钥，最后为已交换密钥，每组内按最新优先排列。例如：

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

{
    "auth_keys": [
        {
            "id": "096ce472-2cbd-412a-8295-6c03a1a07ba4",
            "description": "my-auth-key",
            "device_name": "pi5-001",
            "tags": ["production", "kiosk"],
            "expires_at": "2026-02-26T16:09:52Z",
            "exchanged_at": null,
            "created_at": "2026-02-25T16:09:52Z"
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 100,
        "total_count": 1,
        "total_pages": 1
    }
}

响应包含以下字段：

auth_keys：组织中的授权密钥列表（每页最多 100 个）。 meta：分页详情。

auth_keys 列表中的每个项目包含以下字段：

id：授权密钥的唯一标识符。 description：创建授权密钥时使用的描述信息。 device_name：交换授权密钥时分配给设备的名称。 tags：交换授权密钥时应用到设备的标签。 expires_at：密钥过期日期与时间（ISO 8601 格式）。 exchanged_at：授权密钥交换以关联设备的日期和时间（ISO 8601 格式），如尚未交换则为 null。 created_at：创建授权密钥的日期和时间（ISO 8601 格式）。

备注

secret 仅在授权密钥首次创建时包含在响应中，之后无法再次查看。

meta 对象包含以下字段：

page：响应的当前页码。 per_page：每页的授权密钥数量（最多 100）。 total_count：组织中的授权密钥总数。 total_pages：组织授权密钥的总页数。

若管理 API 访问令牌无效，将返回 401 Unauthorized 响应。

page 和 per_page 查询参数的用法与列出设备相同。

显示授权密钥

如需显示组织中的单个授权密钥，请使用 管理 API 访问令牌 发起以下 HTTP 请求。

请替换下方代码中的参数：

• rporg_accesstokenhere：您的管理 API 访问令牌。
• auth-key-id：授权密钥的唯一标识符。

HTTP

GET /organisation/auth-keys/auth-key-id HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere

curl

curl --header 'Authorization: Bearer rporg_accesstokenhere' https://api.connect.raspberrypi.com/organisation/auth-keys/auth-key-id

若成功，将返回 200 OK 响应，其中包含授权密钥的详细信息，采用 JSON 格式。例如：

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

{
    "id": "096ce472-2cbd-412a-8295-6c03a1a07ba4",
    "description": "my-auth-key",
    "device_name": "pi5-001",
    "tags": ["production", "kiosk"],
    "expires_at": "2026-02-26T16:09:52Z",
    "exchanged_at": null,
    "created_at": "2026-02-25T16:09:52Z"
}

否则，您会收到以下响应之一：

响应	说明
401 Unauthorized	管理 API 访问令牌无效。
404 Not Found	在组织中未找到该授权密钥。

更新授权密钥

如需更新组织中的现有授权密钥，请使用 管理 API 访问令牌 发起以下 HTTP 请求。

请替换下方代码中的参数：

• rporg_accesstokenhere：您的管理 API 访问令牌。
• auth-key-id：授权密钥的唯一标识符。
• my-renamed-auth-key：授权密钥的新描述。
• pi5-001：交换授权密钥时分配给设备的新名称（可选）。
• production、kiosk：交换授权密钥时应用到设备的标签（可选）。

JSON

PATCH /organisation/auth-keys/auth-key-id HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere
Content-Type: application/json

{
    "description": "my-renamed-auth-key",
    "device_name": "pi5-001",
    "tags": ["production", "kiosk"]
}

curl

curl --request PATCH --header 'Authorization: Bearer rporg_accesstokenhere' --header 'Content-Type: application/json' --data '{"description":"my-renamed-auth-key","device_name":"pi5-001","tags":["production","kiosk"]}' https://api.connect.raspberrypi.com/organisation/auth-keys/auth-key-id

若成功，将返回 200 OK 响应，其中包含更新后的授权密钥，采用 JSON 格式：

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

{
    "id": "096ce472-2cbd-412a-8295-6c03a1a07ba4",
    "description": "my-renamed-auth-key",
    "device_name": "pi5-001",
    "tags": ["production", "kiosk"],
    "expires_at": "2026-02-26T16:09:52Z",
    "exchanged_at": null,
    "created_at": "2026-02-25T16:09:52Z"
}

否则，您会收到以下响应之一：

响应	说明	示例
401 Unauthorized	管理 API 访问令牌无效。
404 Not Found	在组织中未找到该授权密钥。
422 Unprocessable Content	授权密钥已过期或已被交换。	{"message":"This auth key can no longer be edited."}
422 Unprocessable Content	授权密钥因其他原因无法更新。	{"message":"Validation failed: Description can't be blank"}

删除授权密钥

如需删除组织中的授权密钥，请使用 管理 API 访问令牌 发起以下 HTTP 请求。

请替换下方代码中的参数：

• rporg_accesstokenhere：您的管理 API 访问令牌。
• auth-key-id：授权密钥的唯一标识符。

HTTP

DELETE /organisation/auth-keys/auth-key-id HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere

curl

curl --request DELETE --header 'Authorization: Bearer rporg_accesstokenhere' https://api.connect.raspberrypi.com/organisation/auth-keys/auth-key-id

您可以删除任何授权密钥，包括已过期或已交换的密钥。删除已交换的授权密钥不会影响已关联的设备。

若成功，将返回 200 OK 响应，其中包含已删除授权密钥的详细信息，采用 JSON 格式。例如：

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

{
    "id": "096ce472-2cbd-412a-8295-6c03a1a07ba4",
    "description": "my-auth-key",
    "device_name": "pi5-001",
    "tags": ["production", "kiosk"],
    "expires_at": "2026-02-26T16:09:52Z",
    "exchanged_at": null,
    "created_at": "2026-02-25T16:09:52Z"
}

否则，您会收到以下响应之一：

响应	说明
401 Unauthorized	管理 API 访问令牌无效。
404 Not Found	在组织中未找到该授权密钥。

列出设备

若需列出组织中的所有设备，请使用 管理API访问令牌 发起以下HTTP请求。

请替换下方代码中的参数：

• rporg_accesstokenhere：您的管理API访问令牌。

HTTP

GET /organisation/devices HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere

curl

curl --header 'Authorization: Bearer rporg_accesstokenhere' https://api.connect.raspberrypi.com/organisation/devices

若成功，将返回200 OK响应，其中包含最多100个按名称字母顺序排列的组织设备，采用JSON格式。例如：

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

{
    "devices": [
        {
            "id": "69739b44-ebb2-468e-9e24-08126dec4925",
            "name": "raspberrypi5",
            "serial_number": "ea636879c4d47a37",
            "tags": ["production", "kiosk"]
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 100,
        "total_count": 1,
        "total_pages": 1
    }
}

响应包含以下字段：

devices：组织中的设备列表（每页最多100个）。 meta：分页详情。

devices 列表中的每个项目包含以下字段：

id：设备的唯一标识符。 name：设备名称。 serial_number：设备序列号。 tags：应用于该设备的标签。

meta 对象包含以下字段：

page：响应的当前页码。 per_page：每页的设备数量（最多100）。 total_count：组织中的设备总数。 total_pages：组织设备的总页数。

若管理 API 访问令牌无效，将返回 401 Unauthorized 响应。

要获取后续页面的设备，请在查询字符串中使用 page 参数：

HTTP

GET /organisation/devices?page=2 HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere

curl

curl --header 'Authorization: Bearer rporg_accesstokenhere' 'https://api.connect.raspberrypi.com/organisation/devices?page=2'

要更改每页返回的设备数量，请在查询字符串中使用 per_page 参数（最多100）：

HTTP

GET /organisation/devices?per_page=10 HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere

curl

curl --header 'Authorization: Bearer rporg_accesstokenhere' 'https://api.connect.raspberrypi.com/organisation/devices?per_page=10'

显示设备

如需显示组织中的单个设备，请使用 管理 API 访问令牌 发起以下 HTTP 请求。

请替换下方代码中的参数：

• rporg_accesstokenhere：您的管理 API 访问令牌。
• device-id：设备的唯一标识符。

HTTP

GET /organisation/devices/device-id HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere

curl

curl --header 'Authorization: Bearer rporg_accesstokenhere' https://api.connect.raspberrypi.com/organisation/devices/device-id

若成功，将返回 200 OK 响应，其中包含设备的详细信息，采用 JSON 格式。例如：

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

{
    "id": "69739b44-ebb2-468e-9e24-08126dec4925",
    "name": "raspberrypi5",
    "serial_number": "ea636879c4d47a37",
    "tags": ["production", "kiosk"],
    "board": {
        "model": "Raspberry Pi 5",
        "revision": "1.0",
        "memory": "8 GB"
    },
    "os": {
        "name": "Raspberry Pi OS",
        "version": "13 (Trixie)"
    },
    "kernel_architecture": "aarch64",
    "filters": {
        "model": "5",
        "memory": "8gb",
        "os": "raspios-13"
    }
}

响应包含的字段与列出设备返回的 devices 列表中每个项目的字段相同。board、os、kernel_architecture 和 filters 字段仅在设备运行 Connect 客户端 2.9.0 及更高版本时才会填充。

否则，您会收到以下响应之一：

响应	说明
401 Unauthorized	管理 API 访问令牌无效。
404 Not Found	在组织中未找到给定的设备 ID。

更新设备

如需更新组织中设备的名称或标签，请使用 管理 API 访问令牌 发起以下 HTTP 请求。

这两个字段均为可选：请求正文中省略的任何字段将保持不变。

tags 字段会替换设备的现有标签，因此请包含所有希望保留的标签。标签名称不得超过 30 个字符，且只能包含小写字母、数字、连字符和下划线。每台设备最多支持 10 个标签。

要移除所有标签，请传入空列表（"tags": []）。

请替换下方代码中的参数：

• rporg_accesstokenhere：您的管理 API 访问令牌。
• device-id：设备的唯一标识符。
• raspberrypi5：设备的新名称（可选）。
• production、kiosk：设备的新标签（可选）。

JSON

PATCH /organisation/devices/device-id HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere
Content-Type: application/json

{
    "name": "raspberrypi5",
    "tags": ["production", "kiosk"]
}

curl

curl --request PATCH --header 'Authorization: Bearer rporg_accesstokenhere' --header 'Content-Type: application/json' --data '{"name":"raspberrypi5","tags":["production","kiosk"]}' https://api.connect.raspberrypi.com/organisation/devices/device-id

若成功，将返回 200 OK 响应，其中包含更新后的设备，采用 JSON 格式：

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

{
    "id": "69739b44-ebb2-468e-9e24-08126dec4925",
    "name": "raspberrypi5",
    "serial_number": "ea636879c4d47a37",
    "tags": ["production", "kiosk"],
    "board": {
        "model": "Raspberry Pi 5",
        "revision": "1.0",
        "memory": "8 GB"
    },
    "os": {
        "name": "Raspberry Pi OS",
        "version": "13 (Trixie)"
    },
    "kernel_architecture": "aarch64",
    "filters": {
        "model": "5",
        "memory": "8gb",
        "os": "raspios-13"
    }
}

否则，您会收到以下响应之一：

响应	说明	示例
401 Unauthorized	管理 API 访问令牌无效。
404 Not Found	在组织中未找到给定的设备 ID。
422 Unprocessable Content	设备无法更新。	{"message":"Validation failed: Name can't be blank"}

删除设备

若需删除组织中的设备并将其从Raspberry Pi Connect注销，请使用 管理API访问令牌 发起以下HTTP请求。

请替换下方代码中的参数：

• rporg_accesstokenhere：您的管理API访问令牌。
• device-id：设备的唯一标识符。

HTTP

DELETE /organisation/devices/device-id HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere

curl

curl --request DELETE --header 'Authorization: Bearer rporg_accesstokenhere' https://api.connect.raspberrypi.com/organisation/devices/device-id

若成功，将返回 200 OK 响应，其中包含已删除设备的详细信息，采用 JSON 格式。例如：

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

{
    "id": "69739b44-ebb2-468e-9e24-08126dec4925",
    "name": "raspberrypi5",
    "serial_number": "ea636879c4d47a37",
    "tags": ["production", "kiosk"],
    "board": {
        "model": "Raspberry Pi 5",
        "revision": "1.0",
        "memory": "8 GB"
    },
    "os": {
        "name": "Raspberry Pi OS",
        "version": "13 (Trixie)"
    },
    "kernel_architecture": "aarch64",
    "filters": {
        "model": "5",
        "memory": "8gb",
        "os": "raspios-13"
    }
}

若管理 API 访问令牌无效，将返回 401 Unauthorized 响应。

若在组织中未找到给定的设备 ID，将返回 404 Not Found 响应。

批量配置

您可以依次配置多台树莓派 5 系列设备（Raspberry Pi 5、Raspberry Pi 500 和 Raspberry Pi 500+），只需将一台树莓派 5 系列设备设置为主机即可。

准备工作

要使用设备身份进行批量配置，您需要以下条件：

• 两台树莓派 5 系列设备（一台作为主机，一台作为接收设备）。
• 一个 Raspberry Pi Connect 组织账户。
• 一根以太网网线（此工作流暂不支持 Wi-Fi）。
• 一根短的高质量 USB-A 转 USB-C 线缆，用于在配置期间传输电源和数据。请勿使用质量差、仅充电或过长的线缆，这些可能导致配置失败。
• 接收设备的启动介质：一张 32 GB 或更大的 microSD 卡。
• 主机设备：一张 32 GB 或更大的 microSD 卡。如需更快的配置速度，请使用 32 GB 或更大的 SSD。

步骤 1：准备设备

1. 断开或移除接收设备和主机设备上的外部 USB 设备或 HAT。

USB 设备和 HAT 会产生额外的功耗，可能干扰配置过程。

步骤 2：在主机设备上安装 rpi-sb-provisioner

提示

镜像生成会消耗大量磁盘空间（每次构建需数 GB 甚至更多），并且在 SSD 上的构建速度明显快于 microSD 卡。Raspberry Pi 500+ 或配备 M.2 HAT+ 的 Raspberry Pi 5 是理想的主机选择。

1. 在命令行中输入以下命令，将最新固件下载到主机设备：

sudo apt update
sudo apt upgrade

2. 在命令行中输入以下命令，在主机设备上安装 Raspberry Pi Secure Boot Provisioner（rpi-sb-provisioner）：

sudo apt update
sudo apt install rpi-sb-provisioner=2.3.0

3. 安装完成后，从主机设备的网页浏览器访问 Raspberry Pi Secure Boot 网页配置 UI：http://localhost:3142

步骤 3：安装 rpi-image-gen

rpi-image-gen 用于构建将烧录到接收设备的操作系统镜像。

1. 在主机设备上，从命令行运行以下命令从 GitHub 克隆 rpi-image-gen 仓库：

git clone https://github.com/raspberrypi/rpi-image-gen.git

2. 进入克隆的目录，然后运行以下命令安装依赖项：

cd rpi-image-gen
sudo ./install_deps.sh

步骤 4：在主机设备上准备和配置镜像

提示

rpi-image-gen 包含一个带有层和配置的示例应用。如需更多信息，请参阅远程更新。

在主机设备上准备镜像：

1. 进入 rpi-image-gen 安装文件夹。
2. 定义构建时要安装的其他软件包。如需更多信息，请参阅 Packages。
3. 添加无线网络凭据。如需更多信息，请参阅 Wireless Networking。
4. 从命令行设置用户账户和密码，并生成构建：

./rpi-image-gen build -S ./examples/ota/ -c ota.yaml -- \
  IGconf_device_user1=admin \
  IGconf_device_user1pass='R@spb3rry*pi'

rpi-image-gen 会在 rpi-image-gen/work/deploy 文件夹中创建一个 .tar.zst 镜像文件。

步骤 5：将镜像导入 provisioner 并配置设备

1. 在主机设备上，打开 provisioner 网页 UI http://localhost:3142/options/get，或从 UI 顶部的选项卡中选择 Get。
2. 在 Gold Master OS Image 框中，选择 Upload New Image，然后将刚刚创建的 .tar.zst 文件（例如 rpi-image-gen/work/deploy-1.0.0/myapp-1.0.0.tar.zst）拖放到框中。

3. 在 Available Images 表中选择该镜像。
4. 向下滚动到 Device & Firmware 表，然后选择以下内容：
   • 设备系列：Raspberry Pi 5。

• 存储类型：SD Card。
• 设备固件：2026-05-26。

5. 向下滚动到 Security Configuration 表，然后选择 Naked。

您的更改会自动保存。

步骤 6：创建管理 API 令牌

要让 provisioner 在配置期间自动向您的 Connect 组织注册设备身份，请创建一个管理 API 访问令牌。

1. 打开 Raspberry Pi Connect，然后选择您的组织。
2. 导航到 API access tokens 部分，然后选择 Provisioning 选项卡。
3. 在 Auth keys 部分选择 New，按照屏幕提示配置密钥，然后选择 Create Auth key。
4. 复制密钥。
5. 打开 provisioner 网页 UI http://localhost:3142/options/get
6. 向下滚动到 Cloud Services 部分，然后将密钥粘贴到 Connect Management API Access Token 字段中。

步骤 7：将接收设备连接到主机设备

接下来，将接收设备置于 USB 启动模式，以便主机设备接管。

1. 将 USB-A 端插入主机设备。
2. 按住接收设备上的电源按钮，同时插入 USB-C 端。通电后松开电源按钮。

接收设备会出现在主机设备的 provisioner UI 中。配置会自动开始。

步骤 8：启动接收设备

配置完成后：

1. 将接收设备从主机设备上拔下。
2. 将接收设备连接到自己的电源。
3. 连接以太网网线。
4. 打开接收设备。

接收设备启动后，它会出现在 Raspberry Pi Connect 的 Devices 选项卡中。

---

中文翻译版以英文版相同知识授权方式共享：CC-BY-SA 4.0。交流 Q群：498908352