API reference
Connectors
Connectors run in your network and publish its apps to Cloudraw. Install, monitor and update them.
List connectors
GET/v0/tenants/{tenant_id}/connectors
Returns every connector of the workspace with its online state, version, update state, trust state and a hosting summary. Online state is refreshed on each call. The full public IP is never included for API tokens; public_ip_masked is.
Token: read-only or full access · Created by: owner or security admin
Path parameters
- tenant_idstringrequired
Your workspace id (Settings → Workspace in the console; it is also in every console URL).
Responses
200 All connectors (not paginated).
application/json
- itemsarray of Connectorrequired
items fields
- idstringrequired
Connector id.
- namestringrequired
Name (lower-case, dashes; derived from the name given at creation, at most 40 characters).
- platformstringrequired
Install platform chosen at creation.
- onlinebooleanrequired
Connected right now.
- enrolledbooleanrequired
Installed: the connector used its enrolment token at least once (stays true while offline).
- hostnamestring | null
Host name the connector reports (last known).
- osstring | null
- os_versionstring | null
- last_seenstring | null (date-time)
Last time it was seen online.
- sw_versionstring | null
Version it runs, Cloudraw build included.
- tunnel_versionstring | null
Bare tunnel version without the Cloudraw build.
- pending_removalone of
Set after a remove in the console: the connector no longer hosts and is deleted for good at
purge_atunless restored. - public_ipstring | null
Always null for API tokens (only owners and security admins in the console see it). Use
public_ip_masked. - public_ip_maskedstring | null
Public egress IP with the last part masked (
203.0.113.x). - public_ip_versioninteger | null
- public_ip_atstring | null (date-time)
When the public IP was last seen.
- public_ip_sourcestring | null
How it was learned (
updater-check). - updateConnectorUpdateStatus
Automatic-update state of one connector.
update fields
- modestring | null
The mode this connector follows now: its own override, else the workspace connector default;
pausedwins over both. - mode_sourcestring
connector= set on this connector;workspace= inherited from the update policy;paused= updates paused on purpose. - mode_overridestring | null
This connector's own mode; null = follows the workspace.
- mode_override_bystring | null
Who set the override.
- mode_override_atstring | null (date-time)
When the override was set.
- rolloutone of
Staged rollout of the newest connector version as it applies to this connector. null = nothing to show (the connector already runs it, or staged rollout is off).
- current_versionstring | null
Version the connector runs, Cloudraw build included (e.g.
1.18.7-b11c); null until it reported one. - build_knownboolean
True when
current_versioncarries the Cloudraw build suffix (-b<n>). - available_versionstring | null
Newer version the connector can update to; null when it is up to date.
- previous_versionstring | null
Version before the last update.
- requested_atstring | null (date-time)
When an "Update now" was requested and not yet applied.
- applied_atstring | null (date-time)
When the last update was applied.
- last_check_atstring | null (date-time)
Last time the connector's updater checked in (every 15 minutes when healthy).
- lastobject
Result of the last update attempt (empty object when there was none).
last fields
- okboolean
- fromstring
- tostring
- messagestring
- atstring (date-time)
- updaterboolean
True when an update token was issued for this connector (an updater can be installed).
- token_rotated_atstring | null (date-time)
When the updater last replaced the token from its install command by its own.
- pausedone of
Set while automatic updates are paused on purpose.
- last_pausedone of
The previous pause, after a resume.
- updater_statestringrequired
ok= checked in within 2 h;stale= no check for over 2 h;never_checked= no check ever arrived (installed before automatic updates: useenable-updates);token_rejected= an updater calls in with an outdated token (run the newestenable-updatescommand once);paused= paused on purpose;none= no updater. - last_reject_atstring | null (date-time)
Last time an updater called in with an outdated token.
- remote_app_helperobject
RemoteApp helper (Windows connector installed on the RDP server itself).
remote_app_helper fields
- enabledbooleanrequired
RemoteApp helper switch (on unless switched off).
- last_seenstring | null (date-time)
- programs_listed_atstring | null (date-time)
- guidesobject
Setup-guide links for this connector.
guides fields
- installobject
A setup-guide link.
install fields
- idstringrequired
- sectionstring | null
- titlestring
- urlstringrequired
Web page of the guide.
- pdf_urlstring | null
PDF version, if any.
- updatesobject
A setup-guide link.
updates fields
- idstringrequired
- sectionstring | null
- titlestring
- urlstringrequired
Web page of the guide.
- pdf_urlstring | null
PDF version, if any.
- high_availabilityobject
A setup-guide link.
high_availability fields
- idstringrequired
- sectionstring | null
- titlestring
- urlstringrequired
Web page of the guide.
- pdf_urlstring | null
PDF version, if any.
- remoteapp_helperobject
A setup-guide link.
remoteapp_helper fields
- idstringrequired
- sectionstring | null
- titlestring
- urlstringrequired
Web page of the guide.
- pdf_urlstring | null
PDF version, if any.
- statusobjectrequired
status fields
- phasestring
pendinguntil the connector first comes online. - observed_atstring | null (date-time)
- messagestring | null
- versionintegerrequired
Increases on every change of the record.
- created_by_integratorone of
Set when an integrator created the connector.
- claim_burned_atstring | null (date-time)
- bitlockerone of
BitLocker readiness of the connector computer from its last diagnostics report; null when none was received.
- short_idstring | null
Last 6 characters of the id, for display. (List and PATCH answers.)
- identity_idstring | null
Id of the connector's enrolled network identity, its key. Two records with the same host name but different identity ids are different machines. (List and PATCH answers.)
- hostname_sharedboolean
True when another enrolled connector or device of the workspace reports the same host name (often a cloned VM). (List and PATCH answers.)
- hostname_shared_witharray of object
The others with that host name (up to 10).
hostname_shared_with fields
- kindstring
- idstring
- short_idstring
- namestring | null
- trustConnectorTrust
trust fields
- statestringrequired
A connector hosts apps and private networks only while
trusted; otherwise it is kept offline. - reasonstring
Why, in plain words.
- sourcestringrequired
What decided: an admin's manual approve / block, the connector trust policy, the default, or a pending removal.
- evaluated_atstring (date-time)
- manualstring | null
Manual decision of an admin, if any (set in the console).
- approvedboolean
Approved by an admin (matters when the trust policy requires approval).
- hosting_summaryone of
List answers only: how many apps / private networks the connector should host vs really hosts, from a recent check; null when none was made recently (call
…/hosting).
- next_pagenull
Always null: the list is not paginated (bounded by your plan's connector limit).
401 unauthorized invalid-token token-expired
unauthorized: No Authorization: Bearer crw_… header was sent.
invalid-token: The token is unknown or was revoked.
token-expired: The token is past its expiry date. Create a new one.
403 insufficient-role tenant-assertion-mismatch
insufficient-role: The token's role ceiling does not allow this call.
tenant-assertion-mismatch: The token belongs to another workspace than {tenant_id}.
404 tenant-not-found
tenant-not-found: No workspace with this id.
curl -sS -X GET "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/connectors" \
-H "Authorization: Bearer $CLOUDRAW_TOKEN"$headers = @{ Authorization = "Bearer $env:CLOUDRAW_TOKEN" }
Invoke-RestMethod -Method Get -Uri "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/connectors" -Headers $headersimport os, uuid, requests
r = requests.get(
"https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/connectors",
headers={"Authorization": f"Bearer {os.environ['CLOUDRAW_TOKEN']}"},
timeout=30,
)
r.raise_for_status()
print(r.json())const res = await fetch("https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/connectors", {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.CLOUDRAW_TOKEN}`,
},
});
if (!res.ok) throw new Error((await res.json()).code);
console.log(await res.json());{
"items": [
{
"id": "cn0r4w8t2kq",
"name": "hq-server-1",
"platform": "windows",
"online": true,
"enrolled": true,
"hostname": "HQ-APP01",
"os": "Windows",
"os_version": "10.0.20348",
"last_seen": "2026-10-13T09:24:11.000Z",
"sw_version": "1.18.7-b11c",
"tunnel_version": "1.18.7",
"pending_removal": null,
"public_ip": null,
"public_ip_masked": "203.0.113.x",
"public_ip_version": 4,
"public_ip_at": "2026-10-13T09:15:02.000Z",
"public_ip_source": "updater-check",
"update": {
"mode": "auto_window",
"mode_source": "workspace",
"mode_override": null,
"mode_override_by": null,
"mode_override_at": null,
"rollout": null,
"current_version": "1.18.7-b11c",
"build_known": true,
"available_version": null,
"previous_version": "1.18.7-b9c",
"requested_at": null,
"applied_at": "2026-10-11T02:14:09.000Z",
"last_check_at": "2026-10-13T09:15:02.000Z",
"last": {
"ok": true,
"from": "1.18.7-b9c",
"to": "1.18.7-b11c",
"message": "updated",
"at": "2026-10-11T02:14:09.000Z"
},
"updater": true,
"token_rotated_at": "2026-10-02T11:40:00.000Z",
"paused": null,
"last_paused": null,
"updater_state": "ok",
"last_reject_at": null
},
"remote_app_helper": {
"enabled": true,
"last_seen": "2026-10-13T09:10:00.000Z",
"programs_listed_at": "2026-10-12T16:02:00.000Z"
},
"guides": {
"install": {
"id": "connector-windows",
"section": null,
"title": "Install a connector on Windows",
"url": "https://cdapi.cloudraw.com/guides/connector-windows",
"pdf_url": "https://cdapi.cloudraw.com/guides/connector-windows.pdf"
},
"updates": {
"id": "connector-updates",
"section": null,
"title": "Connector updates",
"url": "https://cdapi.cloudraw.com/guides/connector-updates",
"pdf_url": "https://cdapi.cloudraw.com/guides/connector-updates.pdf"
},
"high_availability": {
"id": "connector-ha",
"section": null,
"title": "Connector high availability",
"url": "https://cdapi.cloudraw.com/guides/connector-ha",
"pdf_url": "https://cdapi.cloudraw.com/guides/connector-ha.pdf"
},
"remoteapp_helper": {
"id": "connector-remoteapp-helper",
"section": null,
"title": "RemoteApp helper",
"url": "https://cdapi.cloudraw.com/guides/connector-remoteapp-helper",
"pdf_url": "https://cdapi.cloudraw.com/guides/connector-remoteapp-helper.pdf"
}
},
"status": {
"phase": "ready",
"observed_at": "2026-10-13T09:24:11.000Z",
"message": null
},
"version": 14,
"created_by_integrator": null,
"claim_burned_at": null,
"bitlocker": null,
"short_id": "w8t2kq",
"identity_id": "Xk2m9QvR1",
"hostname_shared": false,
"hostname_shared_with": [],
"trust": {
"state": "trusted",
"reason": "connector trusted",
"source": "default",
"evaluated_at": "2026-10-13T09:24:11.000Z",
"manual": null,
"approved": false
},
"hosting_summary": {
"expected": 3,
"hosted": 3,
"missing": 0,
"partial": 0,
"checked_at": "2026-10-13T09:23:40.000Z"
}
}
],
"next_page": null
}Create a connector
POST/v0/tenants/{tenant_id}/connectors
Creates a connector record and returns how to install it. The connector does nothing until you run the install on a machine in your network; it then connects outbound only (no inbound ports).
Install flow, by platform - Windows (platform: windows): run install_command in an Administrator PowerShell on the host. It downloads the install script through the short claim_url and installs the connector as a service with automatic updates. Where PowerShell scripts are blocked by policy, download the signed setup program from installer.url (check installer.sha256) and run installer.silent_command (/S /CODE=<claim_code>). The code is single use for the setup program. - Linux (linux, deb, rpm): run install_command (curl -fsSL <claim_url> | sh) as a sudo-capable user on an x86_64 machine. - Docker (docker, the default): install_command is the same Linux one-liner; alt_install.docker is a docker run command (host networking, restart unless-stopped) with the enrolment token inline.
The claim link is valid 24 hours and at most 20 fetches, and stops working once the connector has installed. The enrolment token (enrollment_jwt) is single use and valid 7 days (expires_at); to get a fresh link later, call POST …/connectors/{connector_id}/install. Watch GET …/connectors until online is true. Audited.
Token: full access · Created by: owner
Idempotency: send Idempotency-Key. The answer carries a secret shown once: a retry with the same key answers 409 already-issued instead of the secret.
Path parameters
- tenant_idstringrequired
Your workspace id (Settings → Workspace in the console; it is also in every console URL).
Headers
- Idempotency-Keystring
A unique value (e.g. a UUID) per logical operation. Retrying with the same key and body within 24 hours returns the first answer instead of doing the work twice.
Request body application/json
- namestringrequired
Connector name. Lower-cased; anything other than a-z and 0-9 becomes a dash; cut to 40 characters.
- platformstring
Where it will run. Default
docker.
Responses
201 Created. The install values are shown once (the answer is not cached and is not replayed).
application/json
- connectorConnectorrequired
connector fields
- idstringrequired
Connector id.
- namestringrequired
Name (lower-case, dashes; derived from the name given at creation, at most 40 characters).
- platformstringrequired
Install platform chosen at creation.
- onlinebooleanrequired
Connected right now.
- enrolledbooleanrequired
Installed: the connector used its enrolment token at least once (stays true while offline).
- hostnamestring | null
Host name the connector reports (last known).
- osstring | null
- os_versionstring | null
- last_seenstring | null (date-time)
Last time it was seen online.
- sw_versionstring | null
Version it runs, Cloudraw build included.
- tunnel_versionstring | null
Bare tunnel version without the Cloudraw build.
- pending_removalone of
Set after a remove in the console: the connector no longer hosts and is deleted for good at
purge_atunless restored. - public_ipstring | null
Always null for API tokens (only owners and security admins in the console see it). Use
public_ip_masked. - public_ip_maskedstring | null
Public egress IP with the last part masked (
203.0.113.x). - public_ip_versioninteger | null
- public_ip_atstring | null (date-time)
When the public IP was last seen.
- public_ip_sourcestring | null
How it was learned (
updater-check). - updateConnectorUpdateStatus
Automatic-update state of one connector.
update fields
- modestring | null
The mode this connector follows now: its own override, else the workspace connector default;
pausedwins over both. - mode_sourcestring
connector= set on this connector;workspace= inherited from the update policy;paused= updates paused on purpose. - mode_overridestring | null
This connector's own mode; null = follows the workspace.
- mode_override_bystring | null
Who set the override.
- mode_override_atstring | null (date-time)
When the override was set.
- rolloutone of
Staged rollout of the newest connector version as it applies to this connector. null = nothing to show (the connector already runs it, or staged rollout is off).
- current_versionstring | null
Version the connector runs, Cloudraw build included (e.g.
1.18.7-b11c); null until it reported one. - build_knownboolean
True when
current_versioncarries the Cloudraw build suffix (-b<n>). - available_versionstring | null
Newer version the connector can update to; null when it is up to date.
- previous_versionstring | null
Version before the last update.
- requested_atstring | null (date-time)
When an "Update now" was requested and not yet applied.
- applied_atstring | null (date-time)
When the last update was applied.
- last_check_atstring | null (date-time)
Last time the connector's updater checked in (every 15 minutes when healthy).
- lastobject
Result of the last update attempt (empty object when there was none).
last fields
- okboolean
- fromstring
- tostring
- messagestring
- atstring (date-time)
- updaterboolean
True when an update token was issued for this connector (an updater can be installed).
- token_rotated_atstring | null (date-time)
When the updater last replaced the token from its install command by its own.
- pausedone of
Set while automatic updates are paused on purpose.
- last_pausedone of
The previous pause, after a resume.
- updater_statestringrequired
ok= checked in within 2 h;stale= no check for over 2 h;never_checked= no check ever arrived (installed before automatic updates: useenable-updates);token_rejected= an updater calls in with an outdated token (run the newestenable-updatescommand once);paused= paused on purpose;none= no updater. - last_reject_atstring | null (date-time)
Last time an updater called in with an outdated token.
- remote_app_helperobject
RemoteApp helper (Windows connector installed on the RDP server itself).
remote_app_helper fields
- enabledbooleanrequired
RemoteApp helper switch (on unless switched off).
- last_seenstring | null (date-time)
- programs_listed_atstring | null (date-time)
- guidesobject
Setup-guide links for this connector.
guides fields
- installobject
A setup-guide link.
install fields
- idstringrequired
- sectionstring | null
- titlestring
- urlstringrequired
Web page of the guide.
- pdf_urlstring | null
PDF version, if any.
- updatesobject
A setup-guide link.
updates fields
- idstringrequired
- sectionstring | null
- titlestring
- urlstringrequired
Web page of the guide.
- pdf_urlstring | null
PDF version, if any.
- high_availabilityobject
A setup-guide link.
high_availability fields
- idstringrequired
- sectionstring | null
- titlestring
- urlstringrequired
Web page of the guide.
- pdf_urlstring | null
PDF version, if any.
- remoteapp_helperobject
A setup-guide link.
remoteapp_helper fields
- idstringrequired
- sectionstring | null
- titlestring
- urlstringrequired
Web page of the guide.
- pdf_urlstring | null
PDF version, if any.
- statusobjectrequired
status fields
- phasestring
pendinguntil the connector first comes online. - observed_atstring | null (date-time)
- messagestring | null
- versionintegerrequired
Increases on every change of the record.
- created_by_integratorone of
Set when an integrator created the connector.
- claim_burned_atstring | null (date-time)
- bitlockerone of
BitLocker readiness of the connector computer from its last diagnostics report; null when none was received.
- short_idstring | null
Last 6 characters of the id, for display. (List and PATCH answers.)
- identity_idstring | null
Id of the connector's enrolled network identity, its key. Two records with the same host name but different identity ids are different machines. (List and PATCH answers.)
- hostname_sharedboolean
True when another enrolled connector or device of the workspace reports the same host name (often a cloned VM). (List and PATCH answers.)
- hostname_shared_witharray of object
The others with that host name (up to 10).
hostname_shared_with fields
- kindstring
- idstring
- short_idstring
- namestring | null
- trustConnectorTrust
trust fields
- statestringrequired
A connector hosts apps and private networks only while
trusted; otherwise it is kept offline. - reasonstring
Why, in plain words.
- sourcestringrequired
What decided: an admin's manual approve / block, the connector trust policy, the default, or a pending removal.
- evaluated_atstring (date-time)
- manualstring | null
Manual decision of an admin, if any (set in the console).
- approvedboolean
Approved by an admin (matters when the trust policy requires approval).
- hosting_summaryone of
List answers only: how many apps / private networks the connector should host vs really hosts, from a recent check; null when none was made recently (call
…/hosting).
- install_commandstring | null
The one command to run on the connector host (see the operation description). Shown once.
- claim_urlstring | null
Short one-time install link the command fetches. Valid 24 hours, dies once the connector is installed or a newer install code is made.
- claim_expires_atstring | null (date-time)
When
claim_url/claim_codeexpire (24 h). - claim_codestring | null
Windows only: the bare 16-character code the signed setup program takes (
/CODE=). Single use. - installerone of
Windows only: the signed setup program, for servers where PowerShell scripts are not allowed. Null for Linux / Docker or when no verified build is published.
- install_stepsarray of object
install_steps fields
- titlestring
- commandstring | null
- notestring
- verifystring
What to wait for afterwards (
connector_online).
- alt_installobject
Create answer only: alternative installs.
alt_install fields
- dockerstring
docker runcommand with the enrolment token inline.
- setup_urlnull
Retired; always null.
- enrollment_jwtstring | null
The connector's enrolment token itself (single use, valid
expires_at). Preferinstall_command; never paste it in chats or tickets. - expires_atstring | null (date-time)
When the enrolment token expires (7 days after creation). After that, remove and re-create the connector in the console.
- reveal_withobject
GET …/installonly: the call that makes a fresh install code.reveal_with fields
- methodstring
- pathstring
400 name-required invalid-platform
name-required: name is missing or empty.
invalid-platform: platform is not docker, linux, deb, rpm or windows.
401 unauthorized invalid-token token-expired
unauthorized: No Authorization: Bearer crw_… header was sent.
invalid-token: The token is unknown or was revoked.
token-expired: The token is past its expiry date. Create a new one.
403 connector-quota-reached insufficient-scope insufficient-role tenant-assertion-mismatch
connector-quota-reached: The workspace already has as many connectors as its plan allows.
insufficient-scope: The token is read-only and this call changes something.
insufficient-role: The token's role ceiling does not allow this call.
tenant-assertion-mismatch: The token belongs to another workspace than {tenant_id}.
404 tenant-not-found
tenant-not-found: No workspace with this id.
409 name-pending-removal idempotency-key-reuse already-issued
name-pending-removal: A removed connector with this name can still be restored. Restore it in the console, or pick another name.
idempotency-key-reuse: The same Idempotency-Key was used with a different body within 24 hours.
already-issued: This Idempotency-Key already created a secret; it is shown only once. Retry with a new key.
502 provisioning-failed
provisioning-failed: Cloudraw could not create the connector identity. Nothing usable was created; retry.
503 busy
busy: Cloudraw is switching servers or cannot save right now. Retry after Retry-After seconds.
curl -sS -X POST "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/connectors" \
-H "Authorization: Bearer $CLOUDRAW_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"name": "Branch Linux 1",
"platform": "linux"
}'$body = @'
{
"name": "Branch Linux 1",
"platform": "linux"
}
'@
$headers = @{ Authorization = "Bearer $env:CLOUDRAW_TOKEN"; "Idempotency-Key" = [guid]::NewGuid().ToString() }
Invoke-RestMethod -Method Post -Uri "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/connectors" -Headers $headers -ContentType "application/json" -Body $bodyimport os, uuid, requests
r = requests.post(
"https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/connectors",
headers={"Authorization": f"Bearer {os.environ['CLOUDRAW_TOKEN']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"name": "Branch Linux 1",
"platform": "linux"
},
timeout=30,
)
r.raise_for_status()
print(r.json())const res = await fetch("https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/connectors", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.CLOUDRAW_TOKEN}`,
"Idempotency-Key": crypto.randomUUID(),
"Content-Type": "application/json",
},
body: JSON.stringify({
"name": "Branch Linux 1",
"platform": "linux"
}),
});
if (!res.ok) throw new Error((await res.json()).code);
console.log(await res.json());{
"connector": {
"id": "cn5t8w2k0pd",
"name": "branch-linux-1",
"platform": "linux",
"online": false,
"enrolled": false,
"hostname": null,
"os": null,
"os_version": null,
"last_seen": null,
"sw_version": null,
"tunnel_version": null,
"pending_removal": null,
"public_ip": null,
"public_ip_masked": null,
"public_ip_version": null,
"public_ip_at": null,
"public_ip_source": null,
"update": {
"mode": "auto_window",
"mode_source": "workspace",
"mode_override": null,
"mode_override_by": null,
"mode_override_at": null,
"rollout": null,
"current_version": null,
"build_known": false,
"available_version": null,
"previous_version": null,
"requested_at": null,
"applied_at": null,
"last_check_at": null,
"last": {},
"updater": true,
"token_rotated_at": null,
"paused": null,
"last_paused": null,
"updater_state": "never_checked",
"last_reject_at": null
},
"remote_app_helper": {
"enabled": true,
"last_seen": null,
"programs_listed_at": null
},
"guides": {
"install": {
"id": "connector-linux",
"section": null,
"title": "Install a connector on Linux",
"url": "https://cdapi.cloudraw.com/guides/connector-linux",
"pdf_url": "https://cdapi.cloudraw.com/guides/connector-linux.pdf"
},
"updates": {
"id": "connector-updates",
"section": null,
"title": "Connector updates",
"url": "https://cdapi.cloudraw.com/guides/connector-updates",
"pdf_url": "https://cdapi.cloudraw.com/guides/connector-updates.pdf"
},
"high_availability": {
"id": "connector-ha",
"section": null,
"title": "Connector high availability",
"url": "https://cdapi.cloudraw.com/guides/connector-ha",
"pdf_url": "https://cdapi.cloudraw.com/guides/connector-ha.pdf"
},
"remoteapp_helper": {
"id": "connector-remoteapp-helper",
"section": null,
"title": "RemoteApp helper",
"url": "https://cdapi.cloudraw.com/guides/connector-remoteapp-helper",
"pdf_url": "https://cdapi.cloudraw.com/guides/connector-remoteapp-helper.pdf"
}
},
"status": {
"phase": "pending",
"observed_at": null,
"message": "waiting for connector to come online"
},
"version": 1,
"created_by_integrator": null,
"claim_burned_at": null,
"bitlocker": null
},
"install_command": "curl -fsSL https://cdapi.cloudraw.com/c/p2x8m0k4d9s1q7wa | sh",
"claim_url": "https://cdapi.cloudraw.com/c/p2x8m0k4d9s1q7wa",
"claim_expires_at": "2026-10-14T09:24:11.000Z",
"claim_code": null,
"installer": null,
"install_steps": [
{
"title": "Install the Cloudraw Connector",
"command": "curl -fsSL https://cdapi.cloudraw.com/c/p2x8m0k4d9s1q7wa | sh",
"note": "One command on any Linux x86_64 machine in your network. Outbound-only. The short link enrolls this connector and expires soon — run it now.",
"verify": "connector_online"
}
],
"alt_install": {
"docker": "docker run -d --name cloudraw-connector-branch-linux-1 --restart unless-stopped --network host -e …='<enrolment token>' … run-host"
},
"setup_url": null,
"enrollment_jwt": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ii4uLiJ9.eyJleHAiOjE3NjA5NTE0NTF9.c2lnbmF0dXJl",
"expires_at": "2026-10-20T09:24:11.000Z"
}Change connector settings
PATCH/v0/tenants/{tenant_id}/connectors/{connector_id}
Changes the settings an admin may change on a connector. Today that is only the RemoteApp helper switch (remote_app_helper); other fields in the body are ignored. Removing, disabling, enabling or approving a connector is not possible with an API token: those need a second-factor check by an admin in the Cloudraw console. Audited.
Token: full access · Created by: owner
Path parameters
- tenant_idstringrequired
Your workspace id (Settings → Workspace in the console; it is also in every console URL).
- connector_idstringrequired
Connector id (from
GET …/connectors).
Request body application/json
- remote_app_helperboolean
Turn the RemoteApp helper of a Windows connector on or off.
Responses
200 The connector after the change.
application/json
- idstringrequired
Connector id.
- namestringrequired
Name (lower-case, dashes; derived from the name given at creation, at most 40 characters).
- platformstringrequired
Install platform chosen at creation.
- onlinebooleanrequired
Connected right now.
- enrolledbooleanrequired
Installed: the connector used its enrolment token at least once (stays true while offline).
- hostnamestring | null
Host name the connector reports (last known).
- osstring | null
- os_versionstring | null
- last_seenstring | null (date-time)
Last time it was seen online.
- sw_versionstring | null
Version it runs, Cloudraw build included.
- tunnel_versionstring | null
Bare tunnel version without the Cloudraw build.
- pending_removalone of
Set after a remove in the console: the connector no longer hosts and is deleted for good at
purge_atunless restored. - public_ipstring | null
Always null for API tokens (only owners and security admins in the console see it). Use
public_ip_masked. - public_ip_maskedstring | null
Public egress IP with the last part masked (
203.0.113.x). - public_ip_versioninteger | null
- public_ip_atstring | null (date-time)
When the public IP was last seen.
- public_ip_sourcestring | null
How it was learned (
updater-check). - updateConnectorUpdateStatus
Automatic-update state of one connector.
update fields
- modestring | null
The mode this connector follows now: its own override, else the workspace connector default;
pausedwins over both. - mode_sourcestring
connector= set on this connector;workspace= inherited from the update policy;paused= updates paused on purpose. - mode_overridestring | null
This connector's own mode; null = follows the workspace.
- mode_override_bystring | null
Who set the override.
- mode_override_atstring | null (date-time)
When the override was set.
- rolloutone of
Staged rollout of the newest connector version as it applies to this connector. null = nothing to show (the connector already runs it, or staged rollout is off).
- current_versionstring | null
Version the connector runs, Cloudraw build included (e.g.
1.18.7-b11c); null until it reported one. - build_knownboolean
True when
current_versioncarries the Cloudraw build suffix (-b<n>). - available_versionstring | null
Newer version the connector can update to; null when it is up to date.
- previous_versionstring | null
Version before the last update.
- requested_atstring | null (date-time)
When an "Update now" was requested and not yet applied.
- applied_atstring | null (date-time)
When the last update was applied.
- last_check_atstring | null (date-time)
Last time the connector's updater checked in (every 15 minutes when healthy).
- lastobject
Result of the last update attempt (empty object when there was none).
last fields
- okboolean
- fromstring
- tostring
- messagestring
- atstring (date-time)
- updaterboolean
True when an update token was issued for this connector (an updater can be installed).
- token_rotated_atstring | null (date-time)
When the updater last replaced the token from its install command by its own.
- pausedone of
Set while automatic updates are paused on purpose.
- last_pausedone of
The previous pause, after a resume.
- updater_statestringrequired
ok= checked in within 2 h;stale= no check for over 2 h;never_checked= no check ever arrived (installed before automatic updates: useenable-updates);token_rejected= an updater calls in with an outdated token (run the newestenable-updatescommand once);paused= paused on purpose;none= no updater. - last_reject_atstring | null (date-time)
Last time an updater called in with an outdated token.
- remote_app_helperobject
RemoteApp helper (Windows connector installed on the RDP server itself).
remote_app_helper fields
- enabledbooleanrequired
RemoteApp helper switch (on unless switched off).
- last_seenstring | null (date-time)
- programs_listed_atstring | null (date-time)
- guidesobject
Setup-guide links for this connector.
guides fields
- installobject
A setup-guide link.
install fields
- idstringrequired
- sectionstring | null
- titlestring
- urlstringrequired
Web page of the guide.
- pdf_urlstring | null
PDF version, if any.
- updatesobject
A setup-guide link.
updates fields
- idstringrequired
- sectionstring | null
- titlestring
- urlstringrequired
Web page of the guide.
- pdf_urlstring | null
PDF version, if any.
- high_availabilityobject
A setup-guide link.
high_availability fields
- idstringrequired
- sectionstring | null
- titlestring
- urlstringrequired
Web page of the guide.
- pdf_urlstring | null
PDF version, if any.
- remoteapp_helperobject
A setup-guide link.
remoteapp_helper fields
- idstringrequired
- sectionstring | null
- titlestring
- urlstringrequired
Web page of the guide.
- pdf_urlstring | null
PDF version, if any.
- statusobjectrequired
status fields
- phasestring
pendinguntil the connector first comes online. - observed_atstring | null (date-time)
- messagestring | null
- versionintegerrequired
Increases on every change of the record.
- created_by_integratorone of
Set when an integrator created the connector.
- claim_burned_atstring | null (date-time)
- bitlockerone of
BitLocker readiness of the connector computer from its last diagnostics report; null when none was received.
- short_idstring | null
Last 6 characters of the id, for display. (List and PATCH answers.)
- identity_idstring | null
Id of the connector's enrolled network identity, its key. Two records with the same host name but different identity ids are different machines. (List and PATCH answers.)
- hostname_sharedboolean
True when another enrolled connector or device of the workspace reports the same host name (often a cloned VM). (List and PATCH answers.)
- hostname_shared_witharray of object
The others with that host name (up to 10).
hostname_shared_with fields
- kindstring
- idstring
- short_idstring
- namestring | null
- trustConnectorTrust
trust fields
- statestringrequired
A connector hosts apps and private networks only while
trusted; otherwise it is kept offline. - reasonstring
Why, in plain words.
- sourcestringrequired
What decided: an admin's manual approve / block, the connector trust policy, the default, or a pending removal.
- evaluated_atstring (date-time)
- manualstring | null
Manual decision of an admin, if any (set in the console).
- approvedboolean
Approved by an admin (matters when the trust policy requires approval).
- hosting_summaryone of
List answers only: how many apps / private networks the connector should host vs really hosts, from a recent check; null when none was made recently (call
…/hosting).
400 invalid-remote-app-helper
invalid-remote-app-helper: remote_app_helper is not true or false.
401 unauthorized invalid-token token-expired
unauthorized: No Authorization: Bearer crw_… header was sent.
invalid-token: The token is unknown or was revoked.
token-expired: The token is past its expiry date. Create a new one.
403 insufficient-scope insufficient-role tenant-assertion-mismatch
insufficient-scope: The token is read-only and this call changes something.
insufficient-role: The token's role ceiling does not allow this call.
tenant-assertion-mismatch: The token belongs to another workspace than {tenant_id}.
404 connector-not-found tenant-not-found
connector-not-found: No connector with this id in the workspace.
tenant-not-found: No workspace with this id.
503 busy
busy: Cloudraw is switching servers or cannot save right now. Retry after Retry-After seconds.
curl -sS -X PATCH "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/connectors/cn0r4w8t2kq" \
-H "Authorization: Bearer $CLOUDRAW_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"remote_app_helper": false
}'$body = @'
{
"remote_app_helper": false
}
'@
$headers = @{ Authorization = "Bearer $env:CLOUDRAW_TOKEN" }
Invoke-RestMethod -Method Patch -Uri "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/connectors/cn0r4w8t2kq" -Headers $headers -ContentType "application/json" -Body $bodyimport os, uuid, requests
r = requests.patch(
"https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/connectors/cn0r4w8t2kq",
headers={"Authorization": f"Bearer {os.environ['CLOUDRAW_TOKEN']}"},
json={
"remote_app_helper": False
},
timeout=30,
)
r.raise_for_status()
print(r.json())const res = await fetch("https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/connectors/cn0r4w8t2kq", {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.CLOUDRAW_TOKEN}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"remote_app_helper": false
}),
});
if (!res.ok) throw new Error((await res.json()).code);
console.log(await res.json());{
"id": "cn0r4w8t2kq",
"name": "hq-server-1",
"platform": "windows",
"online": true,
"enrolled": true,
"hostname": "HQ-APP01",
"os": "Windows",
"os_version": "10.0.20348",
"last_seen": "2026-10-13T09:24:11.000Z",
"sw_version": "1.18.7-b11c",
"tunnel_version": "1.18.7",
"pending_removal": null,
"public_ip": null,
"public_ip_masked": "203.0.113.x",
"public_ip_version": 4,
"public_ip_at": "2026-10-13T09:15:02.000Z",
"public_ip_source": "updater-check",
"update": {
"mode": "auto_window",
"mode_source": "workspace",
"mode_override": null,
"mode_override_by": null,
"mode_override_at": null,
"rollout": null,
"current_version": "1.18.7-b11c",
"build_known": true,
"available_version": null,
"previous_version": "1.18.7-b9c",
"requested_at": null,
"applied_at": "2026-10-11T02:14:09.000Z",
"last_check_at": "2026-10-13T09:15:02.000Z",
"last": {
"ok": true,
"from": "1.18.7-b9c",
"to": "1.18.7-b11c",
"message": "updated",
"at": "2026-10-11T02:14:09.000Z"
},
"updater": true,
"token_rotated_at": "2026-10-02T11:40:00.000Z",
"paused": null,
"last_paused": null,
"updater_state": "ok",
"last_reject_at": null
},
"remote_app_helper": {
"enabled": false,
"last_seen": "2026-10-13T09:10:00.000Z",
"programs_listed_at": "2026-10-12T16:02:00.000Z"
},
"guides": {
"install": {
"id": "connector-windows",
"section": null,
"title": "Install a connector on Windows",
"url": "https://cdapi.cloudraw.com/guides/connector-windows",
"pdf_url": "https://cdapi.cloudraw.com/guides/connector-windows.pdf"
},
"updates": {
"id": "connector-updates",
"section": null,
"title": "Connector updates",
"url": "https://cdapi.cloudraw.com/guides/connector-updates",
"pdf_url": "https://cdapi.cloudraw.com/guides/connector-updates.pdf"
},
"high_availability": {
"id": "connector-ha",
"section": null,
"title": "Connector high availability",
"url": "https://cdapi.cloudraw.com/guides/connector-ha",
"pdf_url": "https://cdapi.cloudraw.com/guides/connector-ha.pdf"
},
"remoteapp_helper": {
"id": "connector-remoteapp-helper",
"section": null,
"title": "RemoteApp helper",
"url": "https://cdapi.cloudraw.com/guides/connector-remoteapp-helper",
"pdf_url": "https://cdapi.cloudraw.com/guides/connector-remoteapp-helper.pdf"
}
},
"status": {
"phase": "ready",
"observed_at": "2026-10-13T09:24:11.000Z",
"message": null
},
"version": 14,
"created_by_integrator": null,
"claim_burned_at": null,
"bitlocker": null,
"short_id": "w8t2kq",
"identity_id": "Xk2m9QvR1",
"hostname_shared": false,
"hostname_shared_with": [],
"trust": {
"state": "trusted",
"reason": "connector trusted",
"source": "default",
"evaluated_at": "2026-10-13T09:24:11.000Z",
"manual": null,
"approved": false
}
}Check what a connector hosts
GET/v0/tenants/{tenant_id}/connectors/{connector_id}/hosting
Compares what the connector should host (the apps, private networks and directory link assigned to it) with what it really holds on the Cloudraw edge, per edge location. Use it when a connector shows online but an app does not open: missing lists items it does not host, partial ones held on fewer edge locations than expected. Results are cached about 30 seconds.
Token: read-only or full access · Created by: owner or security admin
Path parameters
- tenant_idstringrequired
Your workspace id (Settings → Workspace in the console; it is also in every console URL).
- connector_idstringrequired
Connector id (from
GET …/connectors).
Query parameters
- refreshstring
1= read fresh data now instead of the cache (at most every 5 seconds).
Responses
200 Expected vs real hosting.
application/json
- connector_idstringrequired
- onlineboolean
- enrolledboolean
- expected_servicesarray of ConnectorHostedItem
Every app, private network (and its DNS) or directory link this connector is set to host.
expected_services fields
- servicestringrequired
Internal service name.
- kindstringrequired
- display_namestring | null
- typestring | null
- ha_hostsinteger
How many connectors host this item.
- connection_idstring
- private_network_idstring
- link_hintstring
Path under
/v0/tenants/{tenant_id}/that describes the item. - idstring
- namestring
- hostedarray of object
hosted fields
- servicestring
- kindstring
- display_namestring | null
- typestring | null
- ha_hostsinteger
- connection_idstring
- private_network_idstring
- link_hintstring
- idstring
- namestring
- terminatorsarray of object
terminators fields
- routerstring
Cloudraw edge location.
- precedencestring
- costinteger
- created_atstring (date-time)
- partialboolean
Held on fewer edge locations than expected.
- missingarray of string
Service names of items the connector should host but does not.
- missing_detailsarray of ConnectorHostedItem
missing_details fields
- servicestringrequired
Internal service name.
- kindstringrequired
- display_namestring | null
- typestring | null
- ha_hostsinteger
How many connectors host this item.
- connection_idstring
- private_network_idstring
- link_hintstring
Path under
/v0/tenants/{tenant_id}/that describes the item. - idstring
- namestring
- summaryobjectrequired
summary fields
- expectedinteger
- hostedinteger
- missinginteger
- partialinteger
- terminators_totalinteger
- expected_terminators_per_serviceinteger
- routersarray of object
routers fields
- routerstring
- connectedboolean | null
- terminatorsinteger
- checked_atstring | null (date-time)
When the hosting data was read.
401 unauthorized invalid-token token-expired
unauthorized: No Authorization: Bearer crw_… header was sent.
invalid-token: The token is unknown or was revoked.
token-expired: The token is past its expiry date. Create a new one.
403 insufficient-role tenant-assertion-mismatch
insufficient-role: The token's role ceiling does not allow this call.
tenant-assertion-mismatch: The token belongs to another workspace than {tenant_id}.
404 connector-not-found tenant-not-found
connector-not-found: No connector with this id in the workspace.
tenant-not-found: No workspace with this id.
503 hosting-unavailable
hosting-unavailable: Hosting could not be read right now. Retry after Retry-After seconds.
curl -sS -X GET "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/connectors/cn0r4w8t2kq/hosting" \
-H "Authorization: Bearer $CLOUDRAW_TOKEN"$headers = @{ Authorization = "Bearer $env:CLOUDRAW_TOKEN" }
Invoke-RestMethod -Method Get -Uri "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/connectors/cn0r4w8t2kq/hosting" -Headers $headersimport os, uuid, requests
r = requests.get(
"https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/connectors/cn0r4w8t2kq/hosting",
headers={"Authorization": f"Bearer {os.environ['CLOUDRAW_TOKEN']}"},
timeout=30,
)
r.raise_for_status()
print(r.json())const res = await fetch("https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/connectors/cn0r4w8t2kq/hosting", {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.CLOUDRAW_TOKEN}`,
},
});
if (!res.ok) throw new Error((await res.json()).code);
console.log(await res.json());{
"connector_id": "cn0r4w8t2kq",
"online": true,
"enrolled": true,
"expected_services": [
{
"service": "tq7x2m9k4ab.erp-web",
"kind": "connection",
"display_name": "ERP (web)",
"type": "https",
"ha_hosts": 1,
"connection_id": "cx9m2v7d1pa",
"link_hint": "connections/cx9m2v7d1pa",
"id": "cx9m2v7d1pa",
"name": "ERP (web)"
}
],
"hosted": [
{
"service": "tq7x2m9k4ab.erp-web",
"kind": "connection",
"display_name": "ERP (web)",
"type": "https",
"ha_hosts": 1,
"connection_id": "cx9m2v7d1pa",
"link_hint": "connections/cx9m2v7d1pa",
"id": "cx9m2v7d1pa",
"name": "ERP (web)",
"terminators": [
{
"router": "edge-1",
"precedence": "default",
"cost": 0,
"created_at": "2026-10-13T06:00:00.000Z"
},
{
"router": "edge-2",
"precedence": "default",
"cost": 0,
"created_at": "2026-10-13T06:00:01.000Z"
}
],
"partial": true
}
],
"missing": [],
"missing_details": [],
"summary": {
"expected": 1,
"hosted": 1,
"missing": 0,
"partial": 1,
"terminators_total": 2,
"expected_terminators_per_service": 3,
"routers": [
{
"router": "edge-1",
"connected": true,
"terminators": 1
},
{
"router": "edge-2",
"connected": true,
"terminators": 1
},
{
"router": "edge-3",
"connected": true,
"terminators": 0
}
]
},
"checked_at": "2026-10-13T09:24:05.000Z"
}Get install details of a connector
GET/v0/tenants/{tenant_id}/connectors/{connector_id}/install
For a connector that has not installed yet: returns the connector, when its enrolment token expires and the Windows setup program, but no install command or code (install_command, claim_url, claim_code and enrollment_jwt are null). Use POST on the same path (reveal_with) to get a fresh install link. A connector that already installed answers 409: if it is offline, fix its connectivity; reinstalling will not help.
Token: read-only or full access · Created by: owner or security admin
Path parameters
- tenant_idstringrequired
Your workspace id (Settings → Workspace in the console; it is also in every console URL).
- connector_idstringrequired
Connector id (from
GET …/connectors).
Responses
200 Install metadata without secrets.
application/json
- connectorConnectorrequired
connector fields
- idstringrequired
Connector id.
- namestringrequired
Name (lower-case, dashes; derived from the name given at creation, at most 40 characters).
- platformstringrequired
Install platform chosen at creation.
- onlinebooleanrequired
Connected right now.
- enrolledbooleanrequired
Installed: the connector used its enrolment token at least once (stays true while offline).
- hostnamestring | null
Host name the connector reports (last known).
- osstring | null
- os_versionstring | null
- last_seenstring | null (date-time)
Last time it was seen online.
- sw_versionstring | null
Version it runs, Cloudraw build included.
- tunnel_versionstring | null
Bare tunnel version without the Cloudraw build.
- pending_removalone of
Set after a remove in the console: the connector no longer hosts and is deleted for good at
purge_atunless restored. - public_ipstring | null
Always null for API tokens (only owners and security admins in the console see it). Use
public_ip_masked. - public_ip_maskedstring | null
Public egress IP with the last part masked (
203.0.113.x). - public_ip_versioninteger | null
- public_ip_atstring | null (date-time)
When the public IP was last seen.
- public_ip_sourcestring | null
How it was learned (
updater-check). - updateConnectorUpdateStatus
Automatic-update state of one connector.
update fields
- modestring | null
The mode this connector follows now: its own override, else the workspace connector default;
pausedwins over both. - mode_sourcestring
connector= set on this connector;workspace= inherited from the update policy;paused= updates paused on purpose. - mode_overridestring | null
This connector's own mode; null = follows the workspace.
- mode_override_bystring | null
Who set the override.
- mode_override_atstring | null (date-time)
When the override was set.
- rolloutone of
Staged rollout of the newest connector version as it applies to this connector. null = nothing to show (the connector already runs it, or staged rollout is off).
- current_versionstring | null
Version the connector runs, Cloudraw build included (e.g.
1.18.7-b11c); null until it reported one. - build_knownboolean
True when
current_versioncarries the Cloudraw build suffix (-b<n>). - available_versionstring | null
Newer version the connector can update to; null when it is up to date.
- previous_versionstring | null
Version before the last update.
- requested_atstring | null (date-time)
When an "Update now" was requested and not yet applied.
- applied_atstring | null (date-time)
When the last update was applied.
- last_check_atstring | null (date-time)
Last time the connector's updater checked in (every 15 minutes when healthy).
- lastobject
Result of the last update attempt (empty object when there was none).
last fields
- okboolean
- fromstring
- tostring
- messagestring
- atstring (date-time)
- updaterboolean
True when an update token was issued for this connector (an updater can be installed).
- token_rotated_atstring | null (date-time)
When the updater last replaced the token from its install command by its own.
- pausedone of
Set while automatic updates are paused on purpose.
- last_pausedone of
The previous pause, after a resume.
- updater_statestringrequired
ok= checked in within 2 h;stale= no check for over 2 h;never_checked= no check ever arrived (installed before automatic updates: useenable-updates);token_rejected= an updater calls in with an outdated token (run the newestenable-updatescommand once);paused= paused on purpose;none= no updater. - last_reject_atstring | null (date-time)
Last time an updater called in with an outdated token.
- remote_app_helperobject
RemoteApp helper (Windows connector installed on the RDP server itself).
remote_app_helper fields
- enabledbooleanrequired
RemoteApp helper switch (on unless switched off).
- last_seenstring | null (date-time)
- programs_listed_atstring | null (date-time)
- guidesobject
Setup-guide links for this connector.
guides fields
- installobject
A setup-guide link.
install fields
- idstringrequired
- sectionstring | null
- titlestring
- urlstringrequired
Web page of the guide.
- pdf_urlstring | null
PDF version, if any.
- updatesobject
A setup-guide link.
updates fields
- idstringrequired
- sectionstring | null
- titlestring
- urlstringrequired
Web page of the guide.
- pdf_urlstring | null
PDF version, if any.
- high_availabilityobject
A setup-guide link.
high_availability fields
- idstringrequired
- sectionstring | null
- titlestring
- urlstringrequired
Web page of the guide.
- pdf_urlstring | null
PDF version, if any.
- remoteapp_helperobject
A setup-guide link.
remoteapp_helper fields
- idstringrequired
- sectionstring | null
- titlestring
- urlstringrequired
Web page of the guide.
- pdf_urlstring | null
PDF version, if any.
- statusobjectrequired
status fields
- phasestring
pendinguntil the connector first comes online. - observed_atstring | null (date-time)
- messagestring | null
- versionintegerrequired
Increases on every change of the record.
- created_by_integratorone of
Set when an integrator created the connector.
- claim_burned_atstring | null (date-time)
- bitlockerone of
BitLocker readiness of the connector computer from its last diagnostics report; null when none was received.
- short_idstring | null
Last 6 characters of the id, for display. (List and PATCH answers.)
- identity_idstring | null
Id of the connector's enrolled network identity, its key. Two records with the same host name but different identity ids are different machines. (List and PATCH answers.)
- hostname_sharedboolean
True when another enrolled connector or device of the workspace reports the same host name (often a cloned VM). (List and PATCH answers.)
- hostname_shared_witharray of object
The others with that host name (up to 10).
hostname_shared_with fields
- kindstring
- idstring
- short_idstring
- namestring | null
- trustConnectorTrust
trust fields
- statestringrequired
A connector hosts apps and private networks only while
trusted; otherwise it is kept offline. - reasonstring
Why, in plain words.
- sourcestringrequired
What decided: an admin's manual approve / block, the connector trust policy, the default, or a pending removal.
- evaluated_atstring (date-time)
- manualstring | null
Manual decision of an admin, if any (set in the console).
- approvedboolean
Approved by an admin (matters when the trust policy requires approval).
- hosting_summaryone of
List answers only: how many apps / private networks the connector should host vs really hosts, from a recent check; null when none was made recently (call
…/hosting).
- install_commandstring | null
The one command to run on the connector host (see the operation description). Shown once.
- claim_urlstring | null
Short one-time install link the command fetches. Valid 24 hours, dies once the connector is installed or a newer install code is made.
- claim_expires_atstring | null (date-time)
When
claim_url/claim_codeexpire (24 h). - claim_codestring | null
Windows only: the bare 16-character code the signed setup program takes (
/CODE=). Single use. - installerone of
Windows only: the signed setup program, for servers where PowerShell scripts are not allowed. Null for Linux / Docker or when no verified build is published.
- install_stepsarray of object
install_steps fields
- titlestring
- commandstring | null
- notestring
- verifystring
What to wait for afterwards (
connector_online).
- alt_installobject
Create answer only: alternative installs.
alt_install fields
- dockerstring
docker runcommand with the enrolment token inline.
- setup_urlnull
Retired; always null.
- enrollment_jwtstring | null
The connector's enrolment token itself (single use, valid
expires_at). Preferinstall_command; never paste it in chats or tickets. - expires_atstring | null (date-time)
When the enrolment token expires (7 days after creation). After that, remove and re-create the connector in the console.
- reveal_withobject
GET …/installonly: the call that makes a fresh install code.reveal_with fields
- methodstring
- pathstring
401 unauthorized invalid-token token-expired
unauthorized: No Authorization: Bearer crw_… header was sent.
invalid-token: The token is unknown or was revoked.
token-expired: The token is past its expiry date. Create a new one.
403 insufficient-role tenant-assertion-mismatch
insufficient-role: The token's role ceiling does not allow this call.
tenant-assertion-mismatch: The token belongs to another workspace than {tenant_id}.
404 connector-not-found tenant-not-found
connector-not-found: No connector with this id in the workspace.
tenant-not-found: No workspace with this id.
409 already-installed
already-installed: The connector has already installed (its enrolment token is spent).
502 lookup-failed
lookup-failed: Cloudraw could not read the connector identity; retry.
curl -sS -X GET "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/connectors/cn0r4w8t2kq/install" \
-H "Authorization: Bearer $CLOUDRAW_TOKEN"$headers = @{ Authorization = "Bearer $env:CLOUDRAW_TOKEN" }
Invoke-RestMethod -Method Get -Uri "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/connectors/cn0r4w8t2kq/install" -Headers $headersimport os, uuid, requests
r = requests.get(
"https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/connectors/cn0r4w8t2kq/install",
headers={"Authorization": f"Bearer {os.environ['CLOUDRAW_TOKEN']}"},
timeout=30,
)
r.raise_for_status()
print(r.json())const res = await fetch("https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/connectors/cn0r4w8t2kq/install", {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.CLOUDRAW_TOKEN}`,
},
});
if (!res.ok) throw new Error((await res.json()).code);
console.log(await res.json());{
"connector": {
"id": "cn0r4w8t2kq",
"name": "hq-server-2",
"platform": "windows",
"online": false,
"enrolled": false,
"hostname": null,
"os": null,
"os_version": null,
"last_seen": null,
"sw_version": null,
"tunnel_version": null,
"pending_removal": null,
"public_ip": null,
"public_ip_masked": null,
"public_ip_version": null,
"public_ip_at": null,
"public_ip_source": null,
"update": {
"mode": "auto_window",
"mode_source": "workspace",
"mode_override": null,
"mode_override_by": null,
"mode_override_at": null,
"rollout": null,
"current_version": null,
"build_known": false,
"available_version": null,
"previous_version": null,
"requested_at": null,
"applied_at": null,
"last_check_at": null,
"last": {},
"updater": true,
"token_rotated_at": null,
"paused": null,
"last_paused": null,
"updater_state": "never_checked",
"last_reject_at": null
},
"remote_app_helper": {
"enabled": true,
"last_seen": null,
"programs_listed_at": null
},
"guides": {
"install": {
"id": "connector-windows",
"section": null,
"title": "Install a connector on Windows",
"url": "https://cdapi.cloudraw.com/guides/connector-windows",
"pdf_url": "https://cdapi.cloudraw.com/guides/connector-windows.pdf"
},
"updates": {
"id": "connector-updates",
"section": null,
"title": "Connector updates",
"url": "https://cdapi.cloudraw.com/guides/connector-updates",
"pdf_url": "https://cdapi.cloudraw.com/guides/connector-updates.pdf"
},
"high_availability": {
"id": "connector-ha",
"section": null,
"title": "Connector high availability",
"url": "https://cdapi.cloudraw.com/guides/connector-ha",
"pdf_url": "https://cdapi.cloudraw.com/guides/connector-ha.pdf"
},
"remoteapp_helper": {
"id": "connector-remoteapp-helper",
"section": null,
"title": "RemoteApp helper",
"url": "https://cdapi.cloudraw.com/guides/connector-remoteapp-helper",
"pdf_url": "https://cdapi.cloudraw.com/guides/connector-remoteapp-helper.pdf"
}
},
"status": {
"phase": "pending",
"observed_at": null,
"message": "waiting for connector to come online"
},
"version": 1,
"created_by_integrator": null,
"claim_burned_at": null,
"bitlocker": null
},
"install_command": null,
"claim_url": null,
"claim_expires_at": null,
"claim_code": null,
"installer": {
"url": "https://cdapi.cloudraw.com/connector/staged/cloudraw-connector-setup-1.18.7-b11c.exe",
"file_name": "cloudraw-connector-setup-1.18.7-b11c.exe",
"sha256": "9f2c4e1a7b3d5f8e0a6c2b4d9e1f3a5c7b9d0e2f4a6c8b0d2e4f6a8c0b2d4e6f",
"signer": "Cloudraw Ltd",
"version": "1.18.7-b11c",
"silent_command": null,
"silent_command_file": null
},
"install_steps": [
{
"title": "Install the Cloudraw Connector",
"command": null,
"note": "Reveal the install command to get a fresh short install link.",
"verify": "connector_online"
}
],
"setup_url": null,
"enrollment_jwt": null,
"expires_at": "2026-10-19T15:02:00.000Z",
"reveal_with": {
"method": "POST",
"path": "/v0/tenants/tq7x2m9k4ab/connectors/cn0r4w8t2kq/install"
}
}Get a new install command
POST/v0/tenants/{tenant_id}/connectors/{connector_id}/install
For a connector that has not installed yet: makes a fresh short install link (24 hours) and a fresh update token, and returns the install command for its platform: the PowerShell one-liner plus claim_code / installer for Windows, curl … | sh for Linux, and a docker run command with the enrolment token inline for Docker. Any earlier install link of this connector stops working (one live code per connector); an install that already started with an earlier link still completes. The enrolment token keeps its original expiry (expires_at). Audited.
Token: full access · Created by: owner
Idempotency: send Idempotency-Key. The answer carries a secret shown once: a retry with the same key answers 409 already-issued instead of the secret.
Path parameters
- tenant_idstringrequired
Your workspace id (Settings → Workspace in the console; it is also in every console URL).
- connector_idstringrequired
Connector id (from
GET …/connectors).
Headers
- Idempotency-Keystring
A unique value (e.g. a UUID) per logical operation. Retrying with the same key and body within 24 hours returns the first answer instead of doing the work twice.
Responses
200 A fresh install command. Shown once (not cached, not replayed).
application/json
- connectorConnectorrequired
connector fields
- idstringrequired
Connector id.
- namestringrequired
Name (lower-case, dashes; derived from the name given at creation, at most 40 characters).
- platformstringrequired
Install platform chosen at creation.
- onlinebooleanrequired
Connected right now.
- enrolledbooleanrequired
Installed: the connector used its enrolment token at least once (stays true while offline).
- hostnamestring | null
Host name the connector reports (last known).
- osstring | null
- os_versionstring | null
- last_seenstring | null (date-time)
Last time it was seen online.
- sw_versionstring | null
Version it runs, Cloudraw build included.
- tunnel_versionstring | null
Bare tunnel version without the Cloudraw build.
- pending_removalone of
Set after a remove in the console: the connector no longer hosts and is deleted for good at
purge_atunless restored. - public_ipstring | null
Always null for API tokens (only owners and security admins in the console see it). Use
public_ip_masked. - public_ip_maskedstring | null
Public egress IP with the last part masked (
203.0.113.x). - public_ip_versioninteger | null
- public_ip_atstring | null (date-time)
When the public IP was last seen.
- public_ip_sourcestring | null
How it was learned (
updater-check). - updateConnectorUpdateStatus
Automatic-update state of one connector.
update fields
- modestring | null
The mode this connector follows now: its own override, else the workspace connector default;
pausedwins over both. - mode_sourcestring
connector= set on this connector;workspace= inherited from the update policy;paused= updates paused on purpose. - mode_overridestring | null
This connector's own mode; null = follows the workspace.
- mode_override_bystring | null
Who set the override.
- mode_override_atstring | null (date-time)
When the override was set.
- rolloutone of
Staged rollout of the newest connector version as it applies to this connector. null = nothing to show (the connector already runs it, or staged rollout is off).
- current_versionstring | null
Version the connector runs, Cloudraw build included (e.g.
1.18.7-b11c); null until it reported one. - build_knownboolean
True when
current_versioncarries the Cloudraw build suffix (-b<n>). - available_versionstring | null
Newer version the connector can update to; null when it is up to date.
- previous_versionstring | null
Version before the last update.
- requested_atstring | null (date-time)
When an "Update now" was requested and not yet applied.
- applied_atstring | null (date-time)
When the last update was applied.
- last_check_atstring | null (date-time)
Last time the connector's updater checked in (every 15 minutes when healthy).
- lastobject
Result of the last update attempt (empty object when there was none).
last fields
- okboolean
- fromstring
- tostring
- messagestring
- atstring (date-time)
- updaterboolean
True when an update token was issued for this connector (an updater can be installed).
- token_rotated_atstring | null (date-time)
When the updater last replaced the token from its install command by its own.
- pausedone of
Set while automatic updates are paused on purpose.
- last_pausedone of
The previous pause, after a resume.
- updater_statestringrequired
ok= checked in within 2 h;stale= no check for over 2 h;never_checked= no check ever arrived (installed before automatic updates: useenable-updates);token_rejected= an updater calls in with an outdated token (run the newestenable-updatescommand once);paused= paused on purpose;none= no updater. - last_reject_atstring | null (date-time)
Last time an updater called in with an outdated token.
- remote_app_helperobject
RemoteApp helper (Windows connector installed on the RDP server itself).
remote_app_helper fields
- enabledbooleanrequired
RemoteApp helper switch (on unless switched off).
- last_seenstring | null (date-time)
- programs_listed_atstring | null (date-time)
- guidesobject
Setup-guide links for this connector.
guides fields
- installobject
A setup-guide link.
install fields
- idstringrequired
- sectionstring | null
- titlestring
- urlstringrequired
Web page of the guide.
- pdf_urlstring | null
PDF version, if any.
- updatesobject
A setup-guide link.
updates fields
- idstringrequired
- sectionstring | null
- titlestring
- urlstringrequired
Web page of the guide.
- pdf_urlstring | null
PDF version, if any.
- high_availabilityobject
A setup-guide link.
high_availability fields
- idstringrequired
- sectionstring | null
- titlestring
- urlstringrequired
Web page of the guide.
- pdf_urlstring | null
PDF version, if any.
- remoteapp_helperobject
A setup-guide link.
remoteapp_helper fields
- idstringrequired
- sectionstring | null
- titlestring
- urlstringrequired
Web page of the guide.
- pdf_urlstring | null
PDF version, if any.
- statusobjectrequired
status fields
- phasestring
pendinguntil the connector first comes online. - observed_atstring | null (date-time)
- messagestring | null
- versionintegerrequired
Increases on every change of the record.
- created_by_integratorone of
Set when an integrator created the connector.
- claim_burned_atstring | null (date-time)
- bitlockerone of
BitLocker readiness of the connector computer from its last diagnostics report; null when none was received.
- short_idstring | null
Last 6 characters of the id, for display. (List and PATCH answers.)
- identity_idstring | null
Id of the connector's enrolled network identity, its key. Two records with the same host name but different identity ids are different machines. (List and PATCH answers.)
- hostname_sharedboolean
True when another enrolled connector or device of the workspace reports the same host name (often a cloned VM). (List and PATCH answers.)
- hostname_shared_witharray of object
The others with that host name (up to 10).
hostname_shared_with fields
- kindstring
- idstring
- short_idstring
- namestring | null
- trustConnectorTrust
trust fields
- statestringrequired
A connector hosts apps and private networks only while
trusted; otherwise it is kept offline. - reasonstring
Why, in plain words.
- sourcestringrequired
What decided: an admin's manual approve / block, the connector trust policy, the default, or a pending removal.
- evaluated_atstring (date-time)
- manualstring | null
Manual decision of an admin, if any (set in the console).
- approvedboolean
Approved by an admin (matters when the trust policy requires approval).
- hosting_summaryone of
List answers only: how many apps / private networks the connector should host vs really hosts, from a recent check; null when none was made recently (call
…/hosting).
- install_commandstring | null
The one command to run on the connector host (see the operation description). Shown once.
- claim_urlstring | null
Short one-time install link the command fetches. Valid 24 hours, dies once the connector is installed or a newer install code is made.
- claim_expires_atstring | null (date-time)
When
claim_url/claim_codeexpire (24 h). - claim_codestring | null
Windows only: the bare 16-character code the signed setup program takes (
/CODE=). Single use. - installerone of
Windows only: the signed setup program, for servers where PowerShell scripts are not allowed. Null for Linux / Docker or when no verified build is published.
- install_stepsarray of object
install_steps fields
- titlestring
- commandstring | null
- notestring
- verifystring
What to wait for afterwards (
connector_online).
- alt_installobject
Create answer only: alternative installs.
alt_install fields
- dockerstring
docker runcommand with the enrolment token inline.
- setup_urlnull
Retired; always null.
- enrollment_jwtstring | null
The connector's enrolment token itself (single use, valid
expires_at). Preferinstall_command; never paste it in chats or tickets. - expires_atstring | null (date-time)
When the enrolment token expires (7 days after creation). After that, remove and re-create the connector in the console.
- reveal_withobject
GET …/installonly: the call that makes a fresh install code.reveal_with fields
- methodstring
- pathstring
401 unauthorized invalid-token token-expired
unauthorized: No Authorization: Bearer crw_… header was sent.
invalid-token: The token is unknown or was revoked.
token-expired: The token is past its expiry date. Create a new one.
403 insufficient-scope insufficient-role tenant-assertion-mismatch
insufficient-scope: The token is read-only and this call changes something.
insufficient-role: The token's role ceiling does not allow this call.
tenant-assertion-mismatch: The token belongs to another workspace than {tenant_id}.
404 connector-not-found tenant-not-found
connector-not-found: No connector with this id in the workspace.
tenant-not-found: No workspace with this id.
409 already-installed idempotency-key-reuse already-issued
already-installed: The connector has already installed; nothing to reinstall.
idempotency-key-reuse: The same Idempotency-Key was used with a different body within 24 hours.
already-issued: This Idempotency-Key already created a secret; it is shown only once. Retry with a new key.
502 lookup-failed
lookup-failed: Cloudraw could not read the connector identity; retry.
503 busy
busy: Cloudraw is switching servers or cannot save right now. Retry after Retry-After seconds.
curl -sS -X POST "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/connectors/cn0r4w8t2kq/install" \
-H "Authorization: Bearer $CLOUDRAW_TOKEN" \
-H "Idempotency-Key: $(uuidgen)"$headers = @{ Authorization = "Bearer $env:CLOUDRAW_TOKEN"; "Idempotency-Key" = [guid]::NewGuid().ToString() }
Invoke-RestMethod -Method Post -Uri "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/connectors/cn0r4w8t2kq/install" -Headers $headersimport os, uuid, requests
r = requests.post(
"https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/connectors/cn0r4w8t2kq/install",
headers={"Authorization": f"Bearer {os.environ['CLOUDRAW_TOKEN']}", "Idempotency-Key": str(uuid.uuid4())},
timeout=30,
)
r.raise_for_status()
print(r.json())const res = await fetch("https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/connectors/cn0r4w8t2kq/install", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.CLOUDRAW_TOKEN}`,
"Idempotency-Key": crypto.randomUUID(),
},
});
if (!res.ok) throw new Error((await res.json()).code);
console.log(await res.json());{
"connector": {
"id": "cn0r4w8t2kq",
"name": "hq-server-2",
"platform": "windows",
"online": false,
"enrolled": false,
"hostname": null,
"os": null,
"os_version": null,
"last_seen": null,
"sw_version": null,
"tunnel_version": null,
"pending_removal": null,
"public_ip": null,
"public_ip_masked": null,
"public_ip_version": null,
"public_ip_at": null,
"public_ip_source": null,
"update": {
"mode": "auto_window",
"mode_source": "workspace",
"mode_override": null,
"mode_override_by": null,
"mode_override_at": null,
"rollout": null,
"current_version": null,
"build_known": false,
"available_version": null,
"previous_version": null,
"requested_at": null,
"applied_at": null,
"last_check_at": null,
"last": {},
"updater": true,
"token_rotated_at": null,
"paused": null,
"last_paused": null,
"updater_state": "never_checked",
"last_reject_at": null
},
"remote_app_helper": {
"enabled": true,
"last_seen": null,
"programs_listed_at": null
},
"guides": {
"install": {
"id": "connector-windows",
"section": null,
"title": "Install a connector on Windows",
"url": "https://cdapi.cloudraw.com/guides/connector-windows",
"pdf_url": "https://cdapi.cloudraw.com/guides/connector-windows.pdf"
},
"updates": {
"id": "connector-updates",
"section": null,
"title": "Connector updates",
"url": "https://cdapi.cloudraw.com/guides/connector-updates",
"pdf_url": "https://cdapi.cloudraw.com/guides/connector-updates.pdf"
},
"high_availability": {
"id": "connector-ha",
"section": null,
"title": "Connector high availability",
"url": "https://cdapi.cloudraw.com/guides/connector-ha",
"pdf_url": "https://cdapi.cloudraw.com/guides/connector-ha.pdf"
},
"remoteapp_helper": {
"id": "connector-remoteapp-helper",
"section": null,
"title": "RemoteApp helper",
"url": "https://cdapi.cloudraw.com/guides/connector-remoteapp-helper",
"pdf_url": "https://cdapi.cloudraw.com/guides/connector-remoteapp-helper.pdf"
}
},
"status": {
"phase": "pending",
"observed_at": null,
"message": "waiting for connector to come online"
},
"version": 1,
"created_by_integrator": null,
"claim_burned_at": null,
"bitlocker": null
},
"install_command": "powershell -NoProfile -ExecutionPolicy Bypass -Command \"[Net.ServicePointManager]::SecurityProtocol = 3072; irm 'https://cdapi.cloudraw.com/c/k3m9x0d2q8s1w7pa' | iex\"",
"claim_url": "https://cdapi.cloudraw.com/c/k3m9x0d2q8s1w7pa",
"claim_expires_at": "2026-10-14T09:24:11.000Z",
"claim_code": "k3m9x0d2q8s1w7pa",
"installer": {
"url": "https://cdapi.cloudraw.com/connector/staged/cloudraw-connector-setup-1.18.7-b11c.exe",
"file_name": "cloudraw-connector-setup-1.18.7-b11c.exe",
"sha256": "9f2c4e1a7b3d5f8e0a6c2b4d9e1f3a5c7b9d0e2f4a6c8b0d2e4f6a8c0b2d4e6f",
"signer": "Cloudraw Ltd",
"version": "1.18.7-b11c",
"silent_command": "cloudraw-connector-setup-1.18.7-b11c.exe /S /CODE=k3m9x0d2q8s1w7pa",
"silent_command_file": null
},
"install_steps": [
{
"title": "Install the Cloudraw Connector",
"command": "powershell -NoProfile -ExecutionPolicy Bypass -Command \"[Net.ServicePointManager]::SecurityProtocol = 3072; irm 'https://cdapi.cloudraw.com/c/k3m9x0d2q8s1w7pa' | iex\"",
"note": "Run in an Administrator PowerShell on any Windows machine in your network. Outbound-only. The short link enrolls this connector and expires soon — run it now.",
"verify": "connector_online"
}
],
"setup_url": null,
"enrollment_jwt": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ii4uLiJ9.eyJleHAiOjE3NjA5NTE0NTF9.c2lnbmF0dXJl",
"expires_at": "2026-10-19T15:02:00.000Z"
}Get connector trust
GET/v0/tenants/{tenant_id}/connectors/{connector_id}/trust
Returns whether the connector is trusted to host, and why. An untrusted or pending connector is kept offline, so its apps are unreachable. Approving or blocking a connector is done in the Cloudraw console (it needs a second-factor check).
Token: read-only or full access · Created by: owner or security admin
Path parameters
- tenant_idstringrequired
Your workspace id (Settings → Workspace in the console; it is also in every console URL).
- connector_idstringrequired
Connector id (from
GET …/connectors).
Responses
200 Trust state.
application/json
- connector_idstringrequired
- statestringrequired
- reasonstring
- sourcestring
- evaluated_atstring (date-time)
- manualstring | null
- approvedboolean
401 unauthorized invalid-token token-expired
unauthorized: No Authorization: Bearer crw_… header was sent.
invalid-token: The token is unknown or was revoked.
token-expired: The token is past its expiry date. Create a new one.
403 insufficient-role tenant-assertion-mismatch
insufficient-role: The token's role ceiling does not allow this call.
tenant-assertion-mismatch: The token belongs to another workspace than {tenant_id}.
404 connector-not-found tenant-not-found
connector-not-found: No connector with this id in the workspace.
tenant-not-found: No workspace with this id.
curl -sS -X GET "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/connectors/cn0r4w8t2kq/trust" \
-H "Authorization: Bearer $CLOUDRAW_TOKEN"$headers = @{ Authorization = "Bearer $env:CLOUDRAW_TOKEN" }
Invoke-RestMethod -Method Get -Uri "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/connectors/cn0r4w8t2kq/trust" -Headers $headersimport os, uuid, requests
r = requests.get(
"https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/connectors/cn0r4w8t2kq/trust",
headers={"Authorization": f"Bearer {os.environ['CLOUDRAW_TOKEN']}"},
timeout=30,
)
r.raise_for_status()
print(r.json())const res = await fetch("https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/connectors/cn0r4w8t2kq/trust", {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.CLOUDRAW_TOKEN}`,
},
});
if (!res.ok) throw new Error((await res.json()).code);
console.log(await res.json());{
"connector_id": "cn0r4w8t2kq",
"state": "trusted",
"reason": "connector trusted",
"source": "default",
"evaluated_at": "2026-10-13T09:24:11.000Z",
"manual": null,
"approved": false
}List provisioning tokens
GET/v0/tenants/{tenant_id}/provisioning-tokens
Lists the provisioning tokens used to deploy Cloudraw Connect silently to many machines (GPO, Intune, SCCM). Only a prefix of each token is shown; revoked tokens stay in the list with revoked: true.
Token: read-only or full access · Created by: owner or security admin
Path parameters
- tenant_idstringrequired
Your workspace id (Settings → Workspace in the console; it is also in every console URL).
Responses
200 All provisioning tokens (not paginated).
application/json
- itemsarray of ProvisioningTokenrequired
items fields
- idstringrequired
- namestringrequired
- prefixstringrequired
First characters of the token, for recognition (
crwp_xxxxx…). - created_bystring | null
- created_atstring (date-time)
- expires_atstring (date-time)required
- revokedbooleanrequired
- usesinteger
Devices enrolled with it.
- max_usesinteger | null
Null = unlimited.
- next_pagenull
Always null: not paginated.
401 unauthorized invalid-token token-expired
unauthorized: No Authorization: Bearer crw_… header was sent.
invalid-token: The token is unknown or was revoked.
token-expired: The token is past its expiry date. Create a new one.
403 insufficient-role tenant-assertion-mismatch
insufficient-role: The token's role ceiling does not allow this call.
tenant-assertion-mismatch: The token belongs to another workspace than {tenant_id}.
404 tenant-not-found
tenant-not-found: No workspace with this id.
curl -sS -X GET "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/provisioning-tokens" \
-H "Authorization: Bearer $CLOUDRAW_TOKEN"$headers = @{ Authorization = "Bearer $env:CLOUDRAW_TOKEN" }
Invoke-RestMethod -Method Get -Uri "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/provisioning-tokens" -Headers $headersimport os, uuid, requests
r = requests.get(
"https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/provisioning-tokens",
headers={"Authorization": f"Bearer {os.environ['CLOUDRAW_TOKEN']}"},
timeout=30,
)
r.raise_for_status()
print(r.json())const res = await fetch("https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/provisioning-tokens", {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.CLOUDRAW_TOKEN}`,
},
});
if (!res.ok) throw new Error((await res.json()).code);
console.log(await res.json());{
"items": [
{
"id": "prov_k2x9m0s8",
"name": "Intune rollout",
"prefix": "crwp_Q7xk2…",
"created_by": "dana.levi@example.com",
"created_at": "2026-10-13T09:24:11.000Z",
"expires_at": "2026-11-12T09:24:11.000Z",
"revoked": false,
"uses": 37,
"max_uses": 250
}
],
"next_page": null
}Create a provisioning token
POST/v0/tenants/{tenant_id}/provisioning-tokens
Creates a reusable token for unattended Cloudraw Connect installs, and returns the preset file and silent install command to push to your machines. Each machine enrolls itself on first launch with its own one-time code. Mass-enrolled devices start untrusted (no access) until your trust rules pass. The token is shown only in this answer; treat the preset file as a secret. Audited.
Token: full access · Created by: owner
Idempotency: send Idempotency-Key. The answer carries a secret shown once: a retry with the same key answers 409 already-issued instead of the secret.
Path parameters
- tenant_idstringrequired
Your workspace id (Settings → Workspace in the console; it is also in every console URL).
Headers
- Idempotency-Keystring
A unique value (e.g. a UUID) per logical operation. Retrying with the same key and body within 24 hours returns the first answer instead of doing the work twice.
Request body application/json
- namestring
Label, up to 80 characters. Default
Fleet deploy. - ttl_daysinteger
Lifetime in days, 1-365. Default 30.
- max_usesinteger | null
How many devices may enroll with it; null (default) = unlimited.
Responses
201 Created. token is shown once.
application/json
400 invalid-ttl-days invalid-max-uses
invalid-ttl-days: ttl_days is not an integer 1-365.
invalid-max-uses: max_uses is not null or an integer 1-100000.
401 unauthorized invalid-token token-expired
unauthorized: No Authorization: Bearer crw_… header was sent.
invalid-token: The token is unknown or was revoked.
token-expired: The token is past its expiry date. Create a new one.
403 insufficient-scope insufficient-role tenant-assertion-mismatch
insufficient-scope: The token is read-only and this call changes something.
insufficient-role: The token's role ceiling does not allow this call.
tenant-assertion-mismatch: The token belongs to another workspace than {tenant_id}.
404 tenant-not-found
tenant-not-found: No workspace with this id.
409 idempotency-key-reuse already-issued
idempotency-key-reuse: The same Idempotency-Key was used with a different body within 24 hours.
already-issued: This Idempotency-Key already created a secret; it is shown only once. Retry with a new key.
503 busy
busy: Cloudraw is switching servers or cannot save right now. Retry after Retry-After seconds.
curl -sS -X POST "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/provisioning-tokens" \
-H "Authorization: Bearer $CLOUDRAW_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"name": "Intune rollout",
"ttl_days": 30,
"max_uses": 250
}'$body = @'
{
"name": "Intune rollout",
"ttl_days": 30,
"max_uses": 250
}
'@
$headers = @{ Authorization = "Bearer $env:CLOUDRAW_TOKEN"; "Idempotency-Key" = [guid]::NewGuid().ToString() }
Invoke-RestMethod -Method Post -Uri "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/provisioning-tokens" -Headers $headers -ContentType "application/json" -Body $bodyimport os, uuid, requests
r = requests.post(
"https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/provisioning-tokens",
headers={"Authorization": f"Bearer {os.environ['CLOUDRAW_TOKEN']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"name": "Intune rollout",
"ttl_days": 30,
"max_uses": 250
},
timeout=30,
)
r.raise_for_status()
print(r.json())const res = await fetch("https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/provisioning-tokens", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.CLOUDRAW_TOKEN}`,
"Idempotency-Key": crypto.randomUUID(),
"Content-Type": "application/json",
},
body: JSON.stringify({
"name": "Intune rollout",
"ttl_days": 30,
"max_uses": 250
}),
});
if (!res.ok) throw new Error((await res.json()).code);
console.log(await res.json());{
"id": "prov_k2x9m0s8",
"name": "Intune rollout",
"prefix": "crwp_Q7xk2…",
"created_by": "dana.levi@example.com",
"created_at": "2026-10-13T09:24:11.000Z",
"expires_at": "2026-11-12T09:24:11.000Z",
"revoked": false,
"uses": 0,
"max_uses": 250,
"token": "crwp_xxxxxxxxxxxxxxxxxxxxxxxxxx",
"install": {
"client_version": "0.4.9",
"download_url": "https://downloads.cloudraw.com/download/cloudraw-connect-setup-0.4.9.exe",
"preset": {
"schema": 1,
"workspace": "northwind",
"signin": "code",
"enrollment_url": "https://cdapi.cloudraw.com/pub/provision?token=crwp_Q7xk2m9d0s8a1w4e6r2t5y8u3i",
"managed_by": "Northwind Logistics"
},
"preset_path": "C:\\Windows\\Temp\\cloudraw-preset.json",
"installed_preset_path": "C:\\ProgramData\\Cloudraw Connect\\preset.json",
"windows": "cloudraw-connect-setup-0.4.9.exe /S /PRESET=\"C:\\Windows\\Temp\\cloudraw-preset.json\"",
"msi": null,
"note": "Push the preset file to the machine, then run the installer silently (GPO / Intune / SCCM / startup script). Each machine enrolls itself on first launch with its own one-time code. Mass-enrolled devices are untrusted (dark) until your trust rules pass. Treat the preset file as a secret: it carries the provisioning token.",
"provision_endpoint": "https://cdapi.cloudraw.com/pub/provision"
}
}Revoke a provisioning token
DELETE/v0/tenants/{tenant_id}/provisioning-tokens/{token_id}
Revokes the token at once: machines that have not enrolled yet can no longer enroll with it. Devices already enrolled are not affected. The token stays in the list as revoked. Audited.
Token: full access · Created by: owner
Path parameters
- tenant_idstringrequired
Your workspace id (Settings → Workspace in the console; it is also in every console URL).
- token_idstringrequired
Provisioning token id (from
GET …/provisioning-tokens).
Responses
202 Revoked (the task is already done).
application/json
- idstringrequired
- tenant_idstring
- statestringrequired
- result_uristring | null
- errorobject | string | null
Why it failed, or a short status note (e.g.
revoke_pending).
401 unauthorized invalid-token token-expired
unauthorized: No Authorization: Bearer crw_… header was sent.
invalid-token: The token is unknown or was revoked.
token-expired: The token is past its expiry date. Create a new one.
403 insufficient-scope insufficient-role tenant-assertion-mismatch
insufficient-scope: The token is read-only and this call changes something.
insufficient-role: The token's role ceiling does not allow this call.
tenant-assertion-mismatch: The token belongs to another workspace than {tenant_id}.
404 provisioning-token-not-found tenant-not-found
provisioning-token-not-found: No provisioning token with this id.
tenant-not-found: No workspace with this id.
503 busy
busy: Cloudraw is switching servers or cannot save right now. Retry after Retry-After seconds.
curl -sS -X DELETE "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/provisioning-tokens/prov_k2x9m0s8" \
-H "Authorization: Bearer $CLOUDRAW_TOKEN"$headers = @{ Authorization = "Bearer $env:CLOUDRAW_TOKEN" }
Invoke-RestMethod -Method Delete -Uri "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/provisioning-tokens/prov_k2x9m0s8" -Headers $headersimport os, uuid, requests
r = requests.delete(
"https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/provisioning-tokens/prov_k2x9m0s8",
headers={"Authorization": f"Bearer {os.environ['CLOUDRAW_TOKEN']}"},
timeout=30,
)
r.raise_for_status()
print(r.status_code)const res = await fetch("https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/provisioning-tokens/prov_k2x9m0s8", {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.CLOUDRAW_TOKEN}`,
},
});
if (!res.ok) throw new Error((await res.json()).code);
console.log(res.status);{
"id": "task_8k2x0m9s",
"tenant_id": "tq7x2m9k4ab",
"state": "done",
"result_uri": null,
"error": null
}