Raspberry Pi Connect for Organisations

Introduction

Connect for Organisations lets multiple users share access to devices using Raspberry Pi Connect.

Devices in an organisation support all of Connect’s features, including screen sharing, remote shell access, and remote updates. Connect for Organisations also offers:

  • Shared access with roles. Invite users as members or administrators. For more information, see Manage users.

  • Device tagging and search. Organise and find devices by tag, model, memory, or operating system. For more information, see Tag devices and Search and filter devices.

  • Artefact library and self-hosted artefacts. Deploy the same update more than once, and host artefacts yourself so that they don’t expire. For more information, see Deploy remote updates.

  • Audit log. Review 90 days of activity in your organisation. For more information, see View the audit log.

  • Two-factor authentication requirement. Require all members to use 2FA. For more information, see Require two-factor authentication.

  • Provisioning. Link devices without signing in on each one, using auth keys or device identities, and provision many devices at once. For more information, see Provision devices.

  • Management API. Manage devices, auth keys, device identities, and updates automatically. For more information, see Management API.

Creating your first organisation automatically starts a free, four-week trial for that organisation. After the trial, organisations are billed monthly. For more information, see Set up your subscription.

Roles

Every user in an organisation has one of the following roles:

  • Member. Can access all the organisation’s devices using screen sharing and remote shell. Can’t deploy remote updates or make any changes to the organisation.

  • Administrator. Can access all the organisation’s devices, deploy remote updates, and make changes to the organisation. Administrators also receive organisation-wide notification emails for sensitive actions, such as the addition of new devices and new management API access tokens.

Switch between accounts

If you belong to an organisation, the Connect website shows one account at a time: your personal account, or one of your organisations.

To switch between accounts, select the account switcher icon (two opposing arrows) at the top right of the navigation menu, then select the account you want.

The Raspberry Pi Connect interface, showing the account switcher dropdown menu, which lets you change between personal and organisation Connect accounts.
The account switcher.

The procedures in this guide assume that you’ve signed in to connect.raspberrypi.com and switched to your organisation, unless they say otherwise.

Create an organisation

  1. Sign in to connect.raspberrypi.com.

  2. Select the account switcher icon at the top right of the page.

    The Raspberry Pi Connect interface, showing the account switcher dropdown menu with the option to create a new organisation.
  3. Select +New organisation, then enter the organisation’s name.

  4. Select Start your free trial if this is your first organisation, or Create organisation if you’ve created one before.

    Connect creates the organisation and adds you to it as an administrator.

If your personal account has linked devices, Connect offers to transfer them to the new organisation. To transfer them now:

  1. Select the Transfer them all to this organisation link.

    The Raspberry Pi Connect interface, showing a link to transfer devices from a personal account to the new organisation.

    The Transfer personal devices page opens and asks you to confirm the transfer.

    The Raspberry Pi Connect interface, asking you to confirm the transfer of devices to an organisation.
  2. Select the personal devices link to review the devices, or select Transfer x devices (where x is the number of devices) to confirm. Devices you transfer become billable devices in the organisation.

You can also transfer devices later. For more information, see Transfer a device.

Set up your subscription

A Connect for Organisations subscription starts when your four-week trial ends. After that, you’re billed monthly, in arrears. If you don’t set up a subscription before your trial ends, you can’t access the organisation’s devices remotely until you do.

Important
If you still haven’t set up billing, Connect deletes the organisation. About two weeks after the trial ends, Connect sends a deletion warning. About two weeks after that, Connect deletes the organisation, with its devices and memberships.

You must be an administrator to set up a subscription.

  1. Select Set up billing in the trial banner below the tabs at the top of the page.

  2. Enter the email address that you want billing notifications, such as invoices, sent to.

  3. Enter your payment details, then submit them:

    • If your trial hasn’t ended, the button says Start trial. Your trial continues, and monthly billing starts when it ends.

    • If your trial has ended, the button says Pay and subscribe. Your monthly subscription starts immediately.

The Connect billing page, showing the 28-day free trial and the payment details fields.
The billing page.

Manage users

You must be an administrator to invite users, remove users, or change a user’s role.

Invite a user

  1. Select the Users tab, then select Invite someone.

    The Users tab of an organisation in Connect, showing the organisation’s users.
  2. Choose a Role. For a description of each role, see Roles.

  3. Enter the email address to send the invitation to.

  4. Select Send invitation.

    The Invite user page, with a role dropdown menu, an email address field, and a Send invitation button.

Connect emails an invitation to the address you entered. The user can follow the link in the email and sign in with that email address, or with any other Raspberry Pi ID.

Remove a user

  1. Select the Users tab.

  2. Next to the user you want to remove, select the more options icon (three vertical dots), then select Remove…​.

  3. In the confirmation window, select Remove user.

The user is removed from the organisation immediately. Any screen-sharing or remote shell sessions they have with the organisation’s devices end within a few minutes.

Change a user’s role

  1. Select the Users tab.

  2. Next to the user whose role you want to change, select the more options icon (three vertical dots), then select Change role…​.

  3. Select the new role, then select Change role.

Manage devices in an organisation

You must be an administrator to link a device to an organisation. There are three ways to do it:

  • Sign in on the device. Link the device as described in Turn on Connect and link your device. When you choose an account, select the organisation.

  • Provision the device. Use an auth key or a device identity, so that nobody has to sign in on the Connect website. For more information, see Provision devices.

  • Transfer the device. If the device is already linked to your personal account or another organisation, transfer it.

You’re billed for a device from the time it’s linked to your organisation.

Transfer a device

You can transfer a device between your personal account and an organisation, or between organisations. You must be an administrator of each organisation involved.

  1. Switch to the account that currently owns the device.

  2. Select the device in the Devices tab, then select Settings on the device page.

  3. Under Danger zone, select Transfer device…​.

    The Transfer device dialog, showing the accounts that a device can be transferred to.
  4. Select the account to transfer the device to, then select Transfer.

Tag devices

Tags help you categorise and find devices. For example, you can tag devices by location (london, leeds), environment (production, staging), or function (point-of-sale, kiosk). Tags appear below the device name on the device page and in the device list.

You must be an administrator to add or remove tags.

  1. Select the device in the Devices tab, then select Settings on the device page.

    The Edit tags field, showing applied tags and a dropdown menu of suggested tags.
  2. In the Tags field in the General section:

    • To add a tag, start entering its name. Select an existing tag from the dropdown menu, or enter a new tag name and select Create.

    • To remove a tag, select the x next to it.

  3. Select Update Device.

Each device can have up to ten tags. Tag names can be up to 30 characters long, and can only contain lowercase letters, numbers, hyphens, and underscores.

Tip
To apply tags automatically when a device is linked, set them on the auth key or device identity you use to link it. You can set tags, and a device name, when you create an auth key on the Connect website, or with the management API for auth keys and device identities.

Search and filter devices

The search bar at the top of the device list combines free-text search with filters.

To search by device name or serial number, enter any text in the search bar. The results update as you enter text.

To filter by an attribute, enter a qualifier, a colon, and a value:

Qualifier Filters by

model:

Raspberry Pi model (for example, model:5, model:4b)

memory:

RAM size (for example, memory:4gb, memory:512mb)

os:

Operating system (for example, os:raspios-13)

tag:

Tag (for example, tag:kiosk, tag:production)

Note
The model:, memory:, and os: qualifiers only find devices running Connect client version 2.9.0 or later. To update Connect on your devices, see Update the client.

When you start entering text, a dropdown menu suggests qualifiers and values. Select a qualifier to see its values, then select a value to add it as a filter. Applied filters appear in the search bar. To remove a filter, select the x next to it, or press Backspace.

You can combine filters and free text in a single search. For example, model:5 tag:production dashboard finds Raspberry Pi 5 devices tagged production that have 'dashboard' in their name. If you use tag: more than once, Connect only finds devices that have all the tags. For example, tag:production tag:kiosk finds devices that have both tags.

The device list with model and tag filters applied in the search bar.
The device list with filters applied.
Tip
Select a tag on any device in the list to add it as a filter.

Provision devices

Provisioning links devices to your organisation without anyone signing in on the Connect website. This is useful for devices that don’t have a display, and for setting up many devices at once.

You can provision devices with either of the following:

  • Auth keys. A temporary token that links a single device. For more information, see Auth keys.

  • Device identities. A credential tied to a private key in the device’s one-time programmable (OTP) memory, which you can register before the device is deployed. For more information, see Device identities.

You must be an administrator to provision devices. Both auth keys and device identities appear on the organisation’s Provisioning tab.

Choose a provisioning method

Auth keys compared with device identities
Auth key Device identity

Links

A single device. Each auth key can only be used once.

The device whose private key it was created from. A device identity can be used more than once.

Credential on the device

The auth key, which you give to the Connect client when you sign in.

A private key stored in the device’s OTP memory.

How you create it

On the Provisioning tab, or with the management API.

Only with the management API, either directly or through rpi-sb-provisioner.

Billing

From the time the device is linked to your organisation.

Creating device identities is free. Billing starts when the device first authenticates to your organisation.

Suitable for

Linking a few devices, or devices without a display.

Preparing many devices before you deploy them.

Neither method sends a sign-in notification email. Instead, each sign-in is recorded in the organisation’s audit log.

Auth keys

An auth key is a single-use, temporary token that links one device to your organisation. Organisation auth keys start with rpoak_, expire between 1 and 90 days after you create them, and you can have several active at once. For more information about auth keys, and how to use one on a device, see Auth keys.

You can set a device name and tags on an auth key, so that they’re applied automatically when the device is linked.

Create an auth key on the Connect website

  1. Select the Provisioning tab.

  2. In the Auth keys section, select New.

  3. Enter a description and an expiry time, between 1 and 90 days.

  4. (Optional) Under Device settings, enter a Name for the device that the key links, and any Tags to apply to it.

  5. Select Create Auth key.

  6. Select the clipboard icon next to the new auth key to copy it.

    Important
    Connect only shows the auth key once. Copy it now, because you can’t view it again later.

Create auth keys with the management API

To create auth keys automatically, for example from a provisioning script, use the management API.

Device identities

A device identity links a device to your organisation using a private key stored in the device’s one-time programmable (OTP) memory, so nobody has to sign in on the device. Unlike an auth key, a device identity can be used more than once.

Because you only pay for a device from the time it first authenticates to your organisation, you can register device identities while you prepare devices, then ship them. Each device links to your organisation when it first boots and connects to the internet.

Create device identities

You can’t create device identities on the Connect website. Creating one needs a signature made with the device’s private key, which is only available on the device itself. Instead, use one of the following:

  • rpi-sb-provisioner. Registers a device identity for each device as it provisions it. For more information, see Bulk provisioning.

  • The management API. Create a device identity directly. For more information, see Create a device identity.

After you’ve created device identities, you can view them on the Provisioning tab.

Bulk provisioning

You can provision Raspberry Pi 5 family devices (Raspberry Pi 5, Raspberry Pi 500, and Raspberry Pi 500+) one after another, by setting up a single Raspberry Pi 5 family device as a provisioning host. The host writes an operating system image to each recipient device, and registers a device identity for it with your organisation, so that the device links to your organisation automatically when it first boots.

Requirements

  • Two Raspberry Pi 5 family devices: one to act as the host, and one recipient.

  • A Connect organisation account, and administrator access to it.

  • An Ethernet cable, or wireless networking credentials to add to the image in Step 4.

  • A short, high-quality USB-A to USB-C cable to carry power and data during provisioning. Don’t use a flimsy, charge-only, or long cable, because these can cause provisioning to fail.

  • For the recipient device: a microSD card of 32 GB or larger, to boot from.

  • For the host device: a microSD card of 32 GB or larger. For faster provisioning, use an SSD of 32 GB or larger instead.

Step 1: Prepare the devices

Disconnect any USB devices and HATs from both the host and the recipient device. These draw extra power, which can interfere with provisioning.

For more information on rpi-sb-provisioner, see Secure Boot Provisioning.

Step 2: Install rpi-sb-provisioner on the host device

Tip
Building images uses a lot of disk space (several gigabytes for each build), and is noticeably faster on an SSD than on a microSD card. A Raspberry Pi 500+, or a Raspberry Pi 5 with an M.2 HAT+, makes a good host.
  1. Update the software and firmware on the host device. Enter your password if prompted.

    $ sudo apt update
    $ sudo apt upgrade
  2. Install Raspberry Pi Secure Boot Provisioner (rpi-sb-provisioner) on the host device. Enter your password if prompted.

    $ sudo apt update
    $ sudo apt install rpi-sb-provisioner
  3. On the host device, open the provisioner’s web interface in a browser at http://localhost:3142.

    If the web interface opens, rpi-sb-provisioner is installed correctly.

    The Raspberry Pi Secure Boot Provisioner web interface.
    The provisioner’s web interface.

Step 3: Install rpi-image-gen

rpi-image-gen builds the operating system image that the host writes to each recipient device.

  1. On the host device, clone the rpi-image-gen repository from GitHub:

    $ git clone https://github.com/raspberrypi/rpi-image-gen.git
  2. Go to the cloned directory and install the dependencies. Enter your password if prompted.

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

Step 4: Configure and build the image

Tip
rpi-image-gen includes an example application, with layers and configuration, that builds an image compatible with remote updates. For more information, see Set up A/B boot updates.
  1. Go to the rpi-image-gen directory.

  2. Define any additional packages to install at build time. For more information, see Packages.

  3. Add wireless networking credentials. For more information, see Wireless Networking.

  4. Build the image, setting a user account and password for the recipient devices. Replace admin and the example password with your own:

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

    rpi-image-gen saves a .tar.zst image file in the rpi-image-gen/work/deploy directory.

Step 5: Import the image and configure the provisioner

  1. On the host device, open the provisioner web interface at http://localhost:3142/options/get, or select Options from the tabs at the top of the interface.

  2. In the OS Image box, select Upload New Image, then drag the .tar.zst file you built in Step 4 into the box. For example, rpi-image-gen/work/deploy-1.0.0/myapp-1.0.0.tar.zst.

    The image appears in the Available Images table.

    The provisioner web interface, showing OS images listed in the Available Images table.
    The Available Images table, showing the uploaded image.
  3. Select the image in the Available Images table.

  4. In the Device & Firmware table, select the following:

    • Device Family: Raspberry Pi 5

    • Storage Type: SD Card

    • Device Firmware: 2026-05-26

      The Device & Firmware table, showing the device type, storage type, and firmware settings for the recipient device.
      The Device & Firmware table, where you set the recipient device type, storage, and firmware.
  5. In the Security Configuration table, select Naked. This provisions the device without encryption.

    The Security Configuration table of the provisioner web interface, with Naked selected.
    The Naked security configuration.

The provisioner saves your changes automatically.

Step 6: Add a management API access token

The provisioner uses a management API access token to register a device identity for each recipient device with your organisation.

  1. Create a management API access token in your organisation, and copy it.

    Warning
    Keep the access token on the host device only. Never include it in the image you write to recipient devices.
  2. Open the provisioner web interface at http://localhost:3142/options/get.

  3. In the Cloud Services section, paste the access token into the Connect Management API Access Token field.

    The Cloud Services section of the provisioner web interface, showing the field for the management API access token and an optional prefix field.
    The Cloud Services section, where you enter the access token.

Step 7: Connect the recipient device to the host device

Next, put the recipient device into USB boot mode, so that the host device can provision it.

  1. Plug the USB-A end of the cable into the host device.

  2. Hold down the power button on the recipient device while you plug in the USB-C end of the cable. Release the power button when the recipient device powers on.

    The recipient device appears in the provisioner web interface, and provisioning starts automatically.

Step 8: Boot the recipient device

When provisioning is complete:

  1. Unplug the recipient device from the host device.

  2. Connect the recipient device to its own power supply.

  3. Connect an Ethernet cable to the recipient device.

  4. Turn on the recipient device.

When the recipient device has booted, it appears in your organisation’s Devices tab in Connect.

To provision more devices, repeat Steps 7 and 8 for each one.

Deploy remote updates

You can push updates to your organisation’s devices using Connect’s remote update feature. Deploying to an organisation’s devices works much like deploying to a personal device, with the following differences:

Note
Only administrators can deploy remote updates and manage update artefacts.

To deploy an update:

  1. Build an update artefact, as described in Build a script artefact or Set up A/B boot updates.

  2. Choose how to provide the artefact to Connect:

    • Upload an artefact. Connect stores the file for you. Uploads are limited to 2 GB, and expire two hours after you upload them. A device that doesn’t start the deployment within that time doesn’t receive it.

    • Host your own artefact. You store the file somewhere the recipient device can download it from, and give Connect its location. See Host the update artefact. Artefacts you host yourself don’t expire, so choose this option for devices that might be offline for more than two hours, or to deploy the same artefact to many devices over time.

  3. Optionally, add the artefact to the library before you deploy it.

  4. Deploy the artefact.

Host the update artefact

When you host an artefact yourself, Connect doesn’t store the file. Instead, you give Connect the file’s location, and Connect passes it to the recipient device, which downloads the file directly.

You can host the artefact anywhere the recipient device can reach it: your own web server, an S3 bucket, an FTP or SFTP server, or a path on the recipient device itself, using a file:// URI. Remote update supports HTTP, HTTPS, FTP, SFTP, and file URIs.

The location must be reachable from the recipient device, but it doesn’t have to be reachable from the Connect servers or from the internet. For example, you can serve an artefact from another computer on the same local network as the recipient device.

  • The host IP address: 192.168.0.1

  • The port: 8080

  • The path: /path/to/app.update.tar.zst

You also need the artefact’s SHA-256 checksum. Connect passes it to the device, which uses it to check that the artefact wasn’t corrupted or tampered with in transit. otamaker prints the checksum when it builds a script artefact; for other artefacts, calculate it with sha256sum.

Copy down the URI and the checksum. You need both when you deploy the artefact.

Example: serve an artefact from a Raspberry Pi

This example serves an update artefact from a Raspberry Pi on the same network as the recipient device.

  1. On the host Raspberry Pi, start an HTTP server, replacing the directory with the one that contains your artefact:

    $ python -m http.server 8080 --directory ./work/image-myapp
  2. Calculate the artefact’s SHA-256 checksum, then copy it down:

    $ sha256sum ./work/image-myapp/myapp-update.tar.zst
  3. Find the host’s IP address on the local network, then copy it down to use in the artefact’s URI:

    $ hostname -I

Manage the artefact library

The Remote update tab lists your organisation’s artefact library. Connect adds any artefact you create while deploying to the library automatically.

To add an artefact to the library before you deploy it, go to the Remote update tab, select New, then do one of the following:

  • Upload an artefact. Enter a name and choose the file, as described in Upload an artefact, then select Upload artefact.

  • Host your own artefact. Enter a name, the URI, and the SHA-256 checksum, then select Save artefact.

The Host your own artefact screen, showing the Name, URI, and SHA-256 checksum fields.
The Host your own artefact screen, showing the required fields: Name, URI, and SHA-256 checksum.

For uploaded artefacts, the library shows when each one Expires, or when it Expired. Expired artefacts stay in the library so that you can see what was deployed, but you can’t deploy them again. To deploy the same file again, upload it again.

Note
You can’t delete an artefact after you’ve deployed it, or tried to deploy it. This keeps a record of what was deployed, in case your account is compromised.

Deploy an artefact

  1. Go to the Devices tab, then select Deploy next to the recipient device.

    Deploy only appears for devices that are opted in to remote updates.

    The Connect Devices tab, showing a list of devices, one of which has a Deploy button next to it.
    The device list shows a Deploy button for devices that are opted in to remote updates.
  2. On the New deployment screen, choose one of the following, then select Next:

    • Use an existing artefact. Choose an artefact from the library. Each artefact shows its name, the first few characters of its checksum, its URI or file name and size, and, for uploaded artefacts, how long until it expires. Expired artefacts don’t appear.

    • Upload an artefact. Enter a name and choose the file, as described in Upload an artefact.

    • Host your own artefact. Enter a name, the URI, and the SHA-256 checksum.

      Step 1 of the New deployment screen in Connect, showing the options to use an existing artefact, upload an artefact, or host your own artefact.
      The New deployment screen, with options to use an existing artefact, upload an artefact, or host your own.
  3. In Step 2: Review and deploy, check the artefact’s details, then select Deploy.

    For an uploaded artefact, this step also shows when the file expires. The deployment only succeeds if the recipient device comes online and downloads the file before then. If a queued deployment already exists for the device, this step warns you that deploying cancels it.

To track the deployment, see Monitor the deployment.

View the audit log

The audit log lists all activity in your organisation from the past 90 days, most recent first. Events include changes to devices, organisation members, and API access tokens, and the start of remote access sessions. Connect deletes events after 90 days.

You must be an administrator to view the audit log.

To view the audit log, select the Audit log tab.

The Audit log tab, showing the Actions filter dropdown menu and a list of events.

Each event includes:

  • Timestamp. When the event happened.

  • Source. Whether the event happened on the Connect website or through the API.

  • Action. What happened (for example, API access token created), with details.

  • Subject. What the action affected, such as a device, the organisation, or an access token.

  • Actor. The user who performed the action, and the country they performed it from.

To filter events by type of action (for example, Remote shell session started), select the Actions dropdown menu next to Filters, above the list.

To download the list as a CSV file, select Download CSV, above the list.

Change organisation settings

Administrators can change the following settings from the Settings tab.

The Settings tab of an organisation, showing the organisation name and other settings.
The Settings tab of an organisation.

Rename the organisation

Enter a new name in the General section. Renaming the organisation doesn’t affect its devices or members.

Require two-factor authentication

You can require all members of your organisation to turn on two-factor authentication (2FA) for their Raspberry Pi ID. This helps stop a compromised member account from being used to access your organisation’s devices.

To require 2FA:

  1. Select the Settings tab, then select Require two-factor authentication.

    A notice confirms that the settings were updated.

    The Authentication section of the organisation settings, showing the Require two-factor authentication button.

This starts a 14-day grace period, during which members who haven’t set up 2FA see a banner asking them to. When the grace period ends, members who still haven’t set up 2FA can’t access your organisation’s devices or other resources until they turn on 2FA for their Raspberry Pi ID.

The Two-factor authentication required page shown to members without 2FA after the grace period ends, with a link to set up 2FA for their Raspberry Pi ID.
The Two-factor authentication required page.

To stop requiring 2FA:

  1. Select the Settings tab, then select Stop requiring two-factor authentication.

    A notice confirms that the settings were updated.

Note
If you stop requiring 2FA and then require it again, the 14-day grace period starts again.

Create management API access tokens

A management API access token lets you use the management API to manage your organisation automatically, for example to create auth keys and device identities, manage devices, and deploy updates.

Warning
A management API access token is equivalent to an administrator’s username and password for your organisation. It can manage every device, auth key, and device identity in the organisation. Keep it on the computer that calls the management API, such as a provisioning workstation or CI system. Never include it in a Raspberry Pi OS image or copy it onto a device. To authenticate devices themselves, use device-specific credentials, such as auth keys or device identities, which you manage on the Provisioning tab.
  1. In the API access tokens section, select New.

  2. Enter a description for the access token, then select Create Access token.

  3. Select the clipboard icon next to the new access token to copy it.

    Important
    Connect only shows the access token once. Copy it now, because you can’t view it again later.

Management API

The management API lets you manage your organisation automatically, without using the Connect website. You can use it to:

Only administrators can create management API access tokens.

Authentication

Authenticate every request with a management API access token, sent as a bearer token in the Authorization header:

Authorization: Bearer rporg_accesstokenhere

If the access token is invalid, you get a 401 Unauthorized response. Every request can also return 403 Forbidden if the organisation is banned, or if updated Connect terms haven’t been accepted.

The base URL for all requests is https://api.connect.raspberrypi.com.

Rate limits

Each management API access token can make up to 5,000 requests per hour. The limit is measured in fixed one-hour windows: the counter resets at the start of every hour, regardless of when you made your first request in that hour.

Every response to an authenticated request includes the following headers so that you can track your usage:

X-Rate-Limit-Limit

The maximum number of requests allowed for each hour.

X-Rate-Limit-Remaining

The number of requests remaining in the current hour.

X-Rate-Limit-Reset

The number of seconds until the current hour ends and the counter resets.

For example:

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

If you exceed the limit, you get a 429 Too Many Requests response with the same headers. Wait for the number of seconds given in X-Rate-Limit-Reset before retrying. For example:

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

Throttled
Note
Requests made with an invalid access token still count towards the limit for that token, but don’t include the rate limit headers in the response.

Device identities

Use these requests to create and manage device identities. For what device identities are and when to use them, see Device identities.

Create a device identity

The request must include an X-Connect-Identity-Signature header. To generate it, construct a newline-separated payload containing, in this order:

  • The HTTP request method (for example, POST)

  • The full request URL

  • Authorization: <value>

  • Content-Type: <value>

  • Accept: <value> (if your HTTP client sends one)

  • The SHA256 hexadecimal digest of the HTTP request body (the JSON body of the POST shown below)

Sign this payload with the device’s private key using ECDSA with SHA256, then Base64-encode the result.

For example, a request to register a device identity produces the following payload:

POST
https://api.connect.raspberrypi.com/organisation/device-identities
Authorization: Bearer rporg_accesstokenhere
Content-Type: application/json
Accept: */*
<SHA256 hex digest of the HTTP request body>

On the device, use rpi-fw-crypto to sign the payload. For example, with the payload written to payload.txt:

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

The output is the X-Connect-Identity-Signature header value.

To create a device identity for your organisation, use a management API access token to make the following HTTP request.

Replace these values in the code below:

  • rporg_accesstokenhere: your management API access token.

  • signaturehere: the X-Connect-Identity-Signature value for this request.

  • -----BEGIN PUBLIC KEY-----...: the device’s PEM-encoded public key.

  • my-device-identity: a description for the device identity, visible in the organisation’s audit log.

  • pi5-001: the name assigned to the device when the identity is exchanged (optional, defaults to the device’s hostname).

  • production, kiosk: (optional) tags applied to the device when the identity is exchanged. Each tag must contain only lowercase letters, numbers, hyphens, and underscores, with a maximum length of 30 characters. You can apply up to ten tags per device identity.

  • JSON

  • curl

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 --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

If successful, you get a 201 Created response with the device identity in JSON format. For example:

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-----..."
}

The response contains the following fields:

id

A unique identifier for the device identity.

description

The description used to create the device identity.

device_name

The name that is assigned to the device when the identity is exchanged.

tags

The tags that are applied to the device when the identity is exchanged.

created_at

The date and time when the device identity was created (in ISO 8601 format).

public_key

The PEM-encoded public key for the device identity.

Otherwise, you get one of the following responses:

Response Description Example

401 Unauthorized

The management API access token is invalid.

422 Unprocessable Content

The device identity can’t be created.

{"message":"Validation failed: Public key is invalid"}

List device identities

To list all device identities in your organisation, use a management API access token to make the following HTTP request.

Replace these values in the code below:

  • rporg_accesstokenhere: your management API access token.

  • HTTP

  • curl

GET /organisation/device-identities HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere
$ curl --header 'Authorization: Bearer rporg_accesstokenhere' https://api.connect.raspberrypi.com/organisation/device-identities

If successful, you get a 200 OK response with up to 100 of the organisation’s device identities sorted alphabetically by description in JSON format. For example:

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
    }
}

The response contains the following fields:

device_identities

List of device identities in the organisation (up to 100 for each page).

meta

Pagination details.

Each item in the device_identities list contains the following fields:

id

A unique identifier for the device identity.

description

The description used to create the device identity.

device_name

The name that is assigned to the device when the identity is exchanged.

tags

The tags that are applied to the device when the identity is exchanged.

created_at

The date and time when the device identity was created (in ISO 8601 format).

public_key

The PEM-encoded public key for the device identity.

The meta object contains the following fields:

page

The current page number of the response.

per_page

The number of device identities for each page (maximum 100).

total_count

The total number of device identities in the organisation.

total_pages

The total number of pages of device identities for the organisation.

If the management API access token is invalid, you get a 401 Unauthorized response.

The page and per_page query parameters work the same way as for listing devices.

Show a device identity

To show a single device identity in your organisation, use a management API access token to make the following HTTP request.

Replace these values in the code below:

  • rporg_accesstokenhere: your management API access token.

  • device-identity-id: the unique identifier for the device identity.

  • HTTP

  • curl

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

If successful, you get a 200 OK response with the device identity’s details in JSON format. For example:

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-----..."
}

Otherwise, you get one of the following responses:

Response Description

401 Unauthorized

The management API access token is invalid.

404 Not Found

The device identity isn’t found in the organisation.

Update a device identity

To update an existing device identity in your organisation, use a management API access token to make the following HTTP request.

Replace these values in the code below:

  • rporg_accesstokenhere: your management API access token.

  • device-identity-id: the unique identifier for the device identity.

  • my-renamed-device-identity: the new description for the device identity.

  • pi5-001: the new name that is assigned to the device when the identity is exchanged (optional).

  • production, kiosk: tags applied to the device when the identity is exchanged (optional).

  • JSON

  • curl

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 --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

If successful, you get a 200 OK response with the updated device identity in JSON format:

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-----..."
}
Note
Once a device identity has been exchanged for a device, only the description can be updated. Any device_name or tags values in the request body are ignored, because those fields are only applied when the identity is first exchanged.

Otherwise, you get one of the following responses:

Response Description Example

401 Unauthorized

The management API access token is invalid.

404 Not Found

The device identity isn’t found in the organisation.

422 Unprocessable Content

The device identity can’t be updated.

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

Delete a device identity

To delete a device identity in your organisation, use a management API access token to make the following HTTP request.

Replace these values in the code below:

  • rporg_accesstokenhere: your management API access token.

  • device-identity-id: the unique identifier for the device identity.

  • HTTP

  • curl

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

If the device identity has already been exchanged for a device, the linked device is also deleted and signed out of Raspberry Pi Connect.

If successful, you get a 200 OK response with the deleted device identity’s details in JSON format. For example:

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-----..."
}

Otherwise, you get one of the following responses:

Response Description

401 Unauthorized

The management API access token is invalid.

404 Not Found

The device identity isn’t found in the organisation.

Auth keys

Use these requests to create and manage auth keys, which link a single device to your organisation. To create auth keys on the Connect website instead, see Create auth keys.

Create an auth key

To create an auth key to link a device with Connect, use a management API access token to make the following HTTP request.

Replace these values in the code below:

  • rporg_accesstokenhere: your management API access token.

  • my-auth-key: a description for your auth key.

  • 1: how many days until the auth key expires, between 1 and 90 (optional, defaults to 1 day).

  • pi5-001: name used when adding devices with this key (optional, defaults to the device’s hostname).

  • production, kiosk: tags applied to the device when the auth key is exchanged (optional). Each tag must contain only lowercase letters, numbers, hyphens, and underscores, with a maximum length of 30 characters. You can apply up to 10 tags per auth key.

  • JSON

  • HTTP

  • curl

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"]
}
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 --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

If successful, you get a 201 Created response with your auth key in JSON format. For example:

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"
}

The response contains the following fields:

id

A unique identifier for the auth key.

description

The description used to create the auth key.

device_name

The name that is assigned to the device when the auth key is exchanged.

tags

The tags that are applied to the device when the auth key is exchanged.

secret

A random token prefixed with rpoak_.

expires_at

The date and time when the key expires (in ISO 8601 format).

exchanged_at

The date and time when the auth key was exchanged to link a device (in ISO 8601 format), or null if it hasn’t been exchanged yet.

created_at

The date and time when the auth key was created (in ISO 8601 format).

The secret can then be used to link a device with Connect before it expires.

Otherwise, you get one of the following responses:

Response Description Example

401 Unauthorized

The management API access token is invalid.

422 Unprocessable Content

The auth key can’t be created.

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

List auth keys

To list all auth keys in your organisation, use a management API access token to make the following HTTP request.

Replace these values in the code below:

  • rporg_accesstokenhere: your management API access token.

  • HTTP

  • curl

GET /organisation/auth-keys HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere
$ curl --header 'Authorization: Bearer rporg_accesstokenhere' https://api.connect.raspberrypi.com/organisation/auth-keys

If successful, you get a 200 OK response with up to 100 of the organisation’s auth keys in JSON format, sorted with usable auth keys first, followed by expired and then exchanged auth keys, with the most recent first in each group. For example:

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
    }
}

The response contains the following fields:

auth_keys

List of auth keys in the organisation (up to 100 for each page).

meta

Pagination details.

Each item in the auth_keys list contains the following fields:

id

A unique identifier for the auth key.

description

The description used to create the auth key.

device_name

The name that is assigned to the device when the auth key is exchanged.

tags

The tags that are applied to the device when the auth key is exchanged.

expires_at

The date and time when the key expires (in ISO 8601 format).

exchanged_at

The date and time when the auth key was exchanged to link a device (in ISO 8601 format), or null if it hasn’t been exchanged yet.

created_at

The date and time when the auth key was created (in ISO 8601 format).

Note
The secret is only included in the response when an auth key is first created and can’t be viewed again later.

The meta object contains the following fields:

page

The current page number of the response.

per_page

The number of auth keys for each page (maximum 100).

total_count

The total number of auth keys in the organisation.

total_pages

The total number of pages of auth keys for the organisation.

If the management API access token is invalid, you get a 401 Unauthorized response.

The page and per_page query parameters work the same way as for listing devices.

Show an auth key

To show a single auth key in your organisation, use a management API access token to make the following HTTP request.

Replace these values in the code below:

  • rporg_accesstokenhere: your management API access token.

  • auth-key-id: the unique identifier for the auth key.

  • HTTP

  • curl

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

If successful, you get a 200 OK response with the auth key’s details in JSON format. For example:

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"
}

Otherwise, you get one of the following responses:

Response Description

401 Unauthorized

The management API access token is invalid.

404 Not Found

The auth key isn’t found in the organisation.

Update an auth key

To update an existing auth key in your organisation, use a management API access token to make the following HTTP request.

Replace these values in the code below:

  • rporg_accesstokenhere: your management API access token.

  • auth-key-id: the unique identifier for the auth key.

  • my-renamed-auth-key: the new description for the auth key.

  • pi5-001: the new name that is assigned to the device when the auth key is exchanged (optional).

  • production, kiosk: tags applied to the device when the auth key is exchanged (optional).

  • JSON

  • curl

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 --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

If successful, you get a 200 OK response with the updated auth key in JSON format:

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"
}

Otherwise, you get one of the following responses:

Response Description Example

401 Unauthorized

The management API access token is invalid.

404 Not Found

The auth key isn’t found in the organisation.

422 Unprocessable Content

The auth key has expired or has already been exchanged.

{"message":"This auth key can no longer be edited."}

422 Unprocessable Content

The auth key can’t be updated for any other reason.

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

Delete an auth key

To delete an auth key in your organisation, use a management API access token to make the following HTTP request.

Replace these values in the code below:

  • rporg_accesstokenhere: your management API access token.

  • auth-key-id: the unique identifier for the auth key.

  • HTTP

  • curl

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

You can delete any auth key, including ones that have expired or have already been exchanged. Deleting an auth key that has been exchanged doesn’t affect the linked device.

If successful, you get a 200 OK response with the deleted auth key’s details in JSON format. For example:

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"
}

Otherwise, you get one of the following responses:

Response Description

401 Unauthorized

The management API access token is invalid.

404 Not Found

The auth key isn’t found in the organisation.

Devices

Use these requests to list, view, update, and delete the devices in your organisation.

List devices

To list all devices in your organisation, use a management API access token to make the following HTTP request.

Replace these values in the code below:

  • rporg_accesstokenhere: your management API access token.

  • HTTP

  • curl

GET /organisation/devices HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere
$ curl --header 'Authorization: Bearer rporg_accesstokenhere' https://api.connect.raspberrypi.com/organisation/devices

If successful, you get a 200 OK response with up to 100 of the organisation’s devices sorted alphabetically by name in JSON format. For example:

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"],
            "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"
            }
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 100,
        "total_count": 1,
        "total_pages": 1
    }
}

The response contains the following fields:

devices

List of devices in the organisation (up to 100 for each page).

meta

Pagination details.

Each item in the devices list contains the following fields:

id

A unique identifier for the device.

name

The name of the device.

serial_number

The serial number of the device.

tags

The tags applied to the device.

board

The device’s board model, revision, and memory. null if unknown.

os

The operating system name and version running on the device. null if unknown.

kernel_architecture

The kernel architecture reported by the device (for example, aarch64). null if unknown.

filters

The qualifiers that match this device, for use with the query parameter (see below). Only includes attributes that are known for the device, so this object might be empty.

The board, os, kernel_architecture, and filters fields are only populated for devices running Connect client version 2.9.0 or later.

The meta object contains the following fields:

page

The current page number of the response.

per_page

The number of devices for each page (maximum 100).

total_count

The total number of devices in the organisation.

total_pages

The total number of pages of devices for the organisation.

If the management API access token is invalid, you get a 401 Unauthorized response.

To fetch subsequent pages of devices, use the page parameter in the query string:

  • HTTP

  • curl

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

To change the number of devices returned for each page, use the per_page parameter in the query string (with a maximum of 100):

  • HTTP

  • curl

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

To filter the devices returned, use the query parameter in the query string. This accepts the same syntax as the search bar in the web interface, combining free-text search with structured filters:

  • Free text matches against device name and serial number.

  • The model:, memory:, os:, and tag: qualifiers filter by a specific attribute (for example, model:5 or tag:production).

You can combine multiple filters and free text in a single query. The value must be URL-encoded, including the spaces between terms.

For example, to find Raspberry Pi 5 devices tagged production:

  • HTTP

  • curl

GET /organisation/devices?query=model%3A5%20tag%3Aproduction HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere
$ curl --header 'Authorization: Bearer rporg_accesstokenhere' --get --data-urlencode 'query=model:5 tag:production' https://api.connect.raspberrypi.com/organisation/devices

The query parameter composes with the page and per_page parameters, so you can paginate through a filtered list.

The filters object returned for each device lists the exact qualifier values that match it, so you can use those values to build a query. For example, a device with "os": "raspios-13" in its filters matches the query os:raspios-13.

The model: qualifier accepts the following values:

Value Model

a

Raspberry Pi A

b

Raspberry Pi B

a+

Raspberry Pi A+

b+

Raspberry Pi B+

2b

Raspberry Pi 2B

cm1

Raspberry Pi CM1

3b

Raspberry Pi 3B

zero

Raspberry Pi Zero

cm3

Raspberry Pi CM3

zerow

Raspberry Pi Zero W

3b+

Raspberry Pi 3B+

3a+

Raspberry Pi 3A+

cm3+

Raspberry Pi CM3+

4b

Raspberry Pi 4B

zero2w

Raspberry Pi Zero 2 W

400

Raspberry Pi 400

cm4

Raspberry Pi CM4

cm4s

Raspberry Pi CM4S

5

Raspberry Pi 5

cm5

Raspberry Pi CM5

500

Raspberry Pi 500

cm5lite

Raspberry Pi CM5 Lite

cm0

Raspberry Pi CM0

The memory: qualifier accepts the following values:

Value Memory

256mb

256 MB

512mb

512 MB

1gb

1 GB

2gb

2 GB

4gb

4 GB

8gb

8 GB

16gb

16 GB

Note
As with the web interface, the model:, memory:, and os: qualifiers only match devices running Connect client version 2.9.0 or later.

Show a device

To show a single device in your organisation, use a management API access token to make the following HTTP request.

Replace these values in the code below:

  • rporg_accesstokenhere: your management API access token.

  • device-id: the unique identifier for your device.

  • HTTP

  • curl

GET /organisation/devices/device-id HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere
$ curl --header 'Authorization: Bearer rporg_accesstokenhere' https://api.connect.raspberrypi.com/organisation/devices/device-id

If successful, you get a 200 OK response with the device’s details in JSON format. For example:

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"
    }
}

The response contains the same fields as each item in the devices list returned when you list devices. The board, os, kernel_architecture, and filters fields are only populated for devices running Connect client version 2.9.0 or later.

Otherwise, you get one of the following responses:

Response Description

401 Unauthorized

The management API access token is invalid.

404 Not Found

The given device ID is not found in the organisation.

Update a device

To update the name or tags of a device in your organisation, use a management API access token to make the following HTTP request.

Both fields are optional: any field you omit from the request body is left unchanged.

The tags field replaces the device’s existing tags, so include any tags you want to keep. Tag names must be 30 characters or fewer and can only contain lowercase letters, numbers, hyphens, and underscores. Each device supports up to ten tags.

To remove all tags, pass an empty list ("tags": []).

Replace these values in the code below:

  • rporg_accesstokenhere: your management API access token.

  • device-id: the unique identifier for your device.

  • raspberrypi5: the new name for the device (optional).

  • production, kiosk: the new tags for the device (optional).

  • JSON

  • curl

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 --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

If successful, you get a 200 OK response with the updated device in JSON format:

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"
    }
}

Otherwise, you get one of the following responses:

Response Description Example

401 Unauthorized

The management API access token is invalid.

404 Not Found

The given device ID is not found in the organisation.

422 Unprocessable Content

The device can’t be updated.

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

Delete a device

To delete a device in your organisation and sign it out of Raspberry Pi Connect, use a management API access token to make the following HTTP request.

Replace these values in the code below:

  • rporg_accesstokenhere: your management API access token.

  • device-id: the unique identifier for your device.

  • HTTP

  • curl

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

If successful, you get a 200 OK response with the deleted device’s details in JSON format. For example:

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"
    }
}

Otherwise, you get one of the following responses:

Response Description

401 Unauthorized

The management API access token is invalid.

404 Not Found

The given device ID is not found in the organisation.

Artefacts

Use these requests to manage your organisation’s artefact library.

List artefacts

To list all remote update artefacts in your organisation, use a management API access token to make the following HTTP request.

Replace these values in the code below:

  • rporg_accesstokenhere: your management API access token.

  • HTTP

  • curl

GET /organisation/artefacts HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere
$ curl --header 'Authorization: Bearer rporg_accesstokenhere' https://api.connect.raspberrypi.com/organisation/artefacts

If successful, you get a 200 OK response with up to 100 of the organisation’s artefacts in JSON format, sorted alphabetically by name and then by when they were created, oldest first. For example:

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
    }
}

Each artefact has the following fields:

id

A unique identifier for the artefact.

name

The artefact’s name. Names don’t have to be unique within the organisation.

type

How the artefact is provided: uri for an artefact you host yourself, or file for an artefact uploaded to Connect.

uri

The location from which devices download the artefact. For an uploaded artefact, this is a link to the uploaded file, or null once Connect has deleted the file.

checksum

The hex-encoded SHA-256 checksum of the artefact.

expires_at

The date and time when an uploaded artefact expires and can no longer be deployed (in ISO 8601 format), or null for an artefact you host yourself.

created_at

The date and time when the artefact was created (in ISO 8601 format).

To filter the artefacts returned, use the name parameter in the query string. This performs a case-insensitive prefix match against the artefact name:

  • HTTP

  • curl

GET /organisation/artefacts?name=kiosk HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere
$ curl --header 'Authorization: Bearer rporg_accesstokenhere' --get --data-urlencode 'name=kiosk' https://api.connect.raspberrypi.com/organisation/artefacts

The page and per_page query parameters work the same way as for listing devices, and compose with the name parameter so you can paginate through a filtered list.

If the management API access token is invalid, you get a 401 Unauthorized response.

Show an artefact

To show a single remote update artefact in your organisation, use a management API access token to make the following HTTP request.

Replace these values in the code below:

  • rporg_accesstokenhere: your management API access token.

  • artefact-id: the unique identifier for the artefact.

  • HTTP

  • curl

GET /organisation/artefacts/artefact-id HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere
$ curl --header 'Authorization: Bearer rporg_accesstokenhere' https://api.connect.raspberrypi.com/organisation/artefacts/artefact-id

If successful, you get a 200 OK response with the artefact’s details in JSON format. For example:

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"
}

Otherwise, you get one of the following responses:

Response Description

401 Unauthorized

The management API access token is invalid.

404 Not Found

The given artefact ID is not found in the organisation.

Create an artefact

To create a remote update artefact for your organisation, use a management API access token to make the following HTTP request.

Note
The management API can only create artefacts that you host yourself. To upload an artefact, use the Remote update tab.

Replace these values in the code below:

  • rporg_accesstokenhere: your management API access token.

  • kiosk-v1.0: a name for the artefact. Names don’t have to be unique within the organisation.

  • https://example.com/kiosk-v1.0.tar.zst: the URI from which devices download the artefact.

  • d39fc02ad7878db7f6803f54dfce89346a763a603cb8e62221ba893fee9c5cc6: the hex-encoded SHA-256 checksum of the artefact.

  • JSON

  • curl

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 --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

If successful, you get a 201 Created response with the artefact’s details in JSON format. For example:

HTTP/2 201
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"
}

Otherwise, you get one of the following responses:

Response Description Example

401 Unauthorized

The management API access token is invalid.

422 Unprocessable Content

The artefact can’t be created.

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

Delete an artefact

To delete an artefact in your organisation, use a management API access token to make the following HTTP request.

Replace these values in the code below:

  • rporg_accesstokenhere: your management API access token.

  • artefact-id: the artefact’s id (as returned by Create an artefact).

  • HTTP

  • curl

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

If successful, you get a 200 OK response with the deleted artefact’s details in JSON format. For example:

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"
}

Otherwise, you get one of the following responses:

Response Description Example

401 Unauthorized

The management API access token is invalid.

404 Not Found

The given artefact ID is not found in the organisation.

422 Unprocessable Content

The artefact has been deployed to a device.

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

Deployments

Use these requests to deploy update artefacts to devices, and to monitor and cancel deployments.

List deployments

To list remote update deployments for a device in your organisation, use a management API access token to make the following HTTP request.

Replace these values in the code below:

  • rporg_accesstokenhere: your management API access token.

  • device-id: the unique identifier for the device.

  • HTTP

  • curl

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

If successful, you get a 200 OK response with up to 100 of the device’s deployments in JSON format, ordered most recent first. For example:

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
    }
}

The state of each deployment is one of queued, in_progress, succeeded, failed, cancelled, or invalidated. For failed deployments, state_reason contains a human-readable explanation of why the deployment failed (for example, when a checksum mismatch occurs or the deployment is superseded by a newer one); for other states it is null.

To filter the deployments returned, use the state parameter in the query string with one of the states listed above. For backwards compatibility, state=pending returns queued deployments:

  • HTTP

  • curl

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

The page and per_page query parameters work the same way as for listing devices.

Otherwise, you get one of the following responses:

Response Description Example

400 Bad Request

The state parameter isn’t one of the recognised states.

{"message":"Unknown state \"exploded\""}

401 Unauthorized

The management API access token is invalid.

404 Not Found

The given device ID is not found in the organisation.

Show a deployment

To show a single deployment in your organisation, use a management API access token to make the following HTTP request.

Replace these values in the code below:

  • rporg_accesstokenhere: your management API access token.

  • deployment-id: the unique identifier for the deployment.

  • HTTP

  • curl

GET /organisation/deployments/deployment-id HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere
$ curl --header 'Authorization: Bearer rporg_accesstokenhere' https://api.connect.raspberrypi.com/organisation/deployments/deployment-id

If successful, you get a 200 OK response with the deployment’s details in JSON format. For example:

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"
}

Otherwise, you get one of the following responses:

Response Description

401 Unauthorized

The management API access token is invalid.

404 Not Found

The deployment isn’t found in the organisation.

Create a deployment

To deploy an artefact to a device, use a management API access token to make the following HTTP request. The new deployment supersedes any deployment already queued for the device.

Replace these values in the code below:

  • rporg_accesstokenhere: your management API access token.

  • device-id: the unique identifier for the recipient device.

  • artefact-id: the artefact’s id (as returned by Create an artefact).

  • JSON

  • curl

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 --header 'Authorization: Bearer rporg_accesstokenhere' --data-urlencode 'artefact_id=artefact-id' https://api.connect.raspberrypi.com/organisation/devices/device-id/deployments

If successful, you get a 201 Created response with the deployment’s details in JSON format. For example:

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"
}

Otherwise, you get one of the following responses:

Response Description Example

400 Bad Request

artefact_id is missing.

401 Unauthorized

The management API access token is invalid.

404 Not Found

The device or artefact is not found in the organisation, or the artefact has expired.

403 Forbidden

Your organisation’s free trial has ended and billing has not been set up.

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

Cancel a deployment

To cancel a queued deployment, use a management API access token to make the following HTTP request.

Replace these values in the code below:

  • rporg_accesstokenhere: your management API access token.

  • deployment-id: the unique identifier for the deployment.

  • HTTP

  • curl

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

If successful, you get a 200 OK response with the updated deployment’s details in JSON format:

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"
}

Otherwise, you get one of the following responses:

Response Description Example

401 Unauthorized

The management API access token is invalid.

404 Not Found

The deployment isn’t found in the organisation.

422 Unprocessable Content

The deployment can’t be cancelled because it isn’t queued. Only queued deployments can be cancelled.

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