API reference

Sessions

Live sessions to your apps; end one.

GETList access history
GETList live sessions
DELETEEnd a session

List access history

GET/v0/tenants/{tenant_id}/access-history

read-only token

Who used which app or private network, from which device, when and for how long — open sessions (live: true) and closed ones, newest first, with per-app totals. Where the connector reports it, entries also carry the exact destination address inside your network and byte counts. History is kept 30 days; sessions shorter than about 30 seconds may be missing, and Cloudraw Connect's automatic reachability checks are left out.

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).
Example: tq7x2m9k4ab

Query parameters

daysinteger
Look-back window in days, 1-30 (out-of-range values are clamped). Default 7.
Example: 7
device_idstring
Only this device.
Example: dvc_5mxq2b7r8k
person_idstring
Only this person.
Example: pz81kd03mna
connection_idstring
Only this app (connection).
Example: cx9m2v7d1pa
kindstring
Only this kind of session.
include_probesboolean
true = also list the automatic Cloudraw Connect reachability checks, each labelled probe: true (for exports); they never count in by_app.
limitinteger
Maximum entries, 1-1000 (clamped). Default 200. There is no next page: narrow the window or filters instead.
Example: 200

Responses

200 Access history for the window (not paginated).

application/json

daysintegerrequired
The window actually used (1-30).
itemsarray of AccessHistoryEntryrequired
Newest first.
items fields
- idstringrequired
  Session id (ovl_…).
- livebooleanrequired
  true = still open.
- kindstring
  device = Cloudraw Connect or vendor access, browser = portal browser access, other = reported by a connector for a client Cloudraw could not match to a device.
  One of: device, browser, other.
- device_idstring | null
- device_namestring | null
- person_idstring | null
- userstring | null
  Person display name or e-mail.
- appstring | null
  App (connection) or private network name.
- connection_idstring | null
- private_network_idstring | null
- targetone of
  What the app or private network points at.
- viastring
  How the person connected.
  One of: cloudraw connect, browser, vendor access.
- ipstring | null
  Public IP address, for browser sessions.
- edgestring | null
  The Cloudraw edge node the session entered through.
- pathstring | null
  The Cloudraw edge nodes the session crossed.
- started_atstring (date-time)required
- ended_atstring | null (date-time)
  null while open.
- duration_sinteger | null
  Seconds; null while open.
- dstone of
  The exact destination inside your network, when the connector reported it.
- bytes_ininteger | null
  Bytes received, as reported by the connector.
- bytes_outinteger | null
  Bytes sent, as reported by the connector.
- end_reasonstring | null
  Why the connector saw the session end.
- reported_bystring | null
  The connector that reported destination and byte counts.
- probeboolean
  Only with include_probes=true: true = an automatic Cloudraw Connect reachability check (not a session; never in by_app).
- probe_anomalyboolean
  This device + app had more than one check-like connection per 2-minute beat (not the cadence of Cloudraw Connect): worth a look.
by_apparray of object
Totals per app over the returned window (before limit), most sessions first.
by_app fields
- appstring
  App name, or (unknown).
- sessionsinteger
- total_sinteger
  Sum of session durations in seconds.
probes_excludedinteger
Automatic reachability checks by Cloudraw Connect that were left out (they are not sessions); 0 with include_probes=true.
probes_includedinteger
Only with include_probes=true: how many listed entries are reachability checks (probe: true).
retention_daysinteger
How long history is kept (30).
notestring
Known limits of the history.

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

curl -sS -X GET "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/access-history" \
  -H "Authorization: Bearer $CLOUDRAW_TOKEN"

PowerShell

$headers = @{ Authorization = "Bearer $env:CLOUDRAW_TOKEN" }
Invoke-RestMethod -Method Get -Uri "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/access-history" -Headers $headers

Python

import os, uuid, requests

r = requests.get(
    "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/access-history",
    headers={"Authorization": f"Bearer {os.environ['CLOUDRAW_TOKEN']}"},
    timeout=30,
)
r.raise_for_status()
print(r.json())

Node.js

const res = await fetch("https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/access-history", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CLOUDRAW_TOKEN}`,
  },
});
if (!res.ok) throw new Error((await res.json()).code);
console.log(await res.json());

Response 200 · application/json

{
  "days": 7,
  "items": [
    {
      "id": "ovl_7f3k9x2m0qd8s1a",
      "live": false,
      "kind": "device",
      "device_id": "dvc_5mxq2b7r8k",
      "device_name": "DANA-LAPTOP",
      "person_id": "pz81kd03mna",
      "user": "Dana Levi",
      "app": "Office LAN",
      "connection_id": null,
      "private_network_id": "pn_6b2x9q0wea",
      "target": {
        "type": "private_network",
        "cidrs": [
          "10.20.0.0/24"
        ],
        "translated_cidr": null
      },
      "via": "cloudraw connect",
      "ip": null,
      "edge": "edge-1",
      "path": "edge-1 → edge-3",
      "started_at": "2026-10-13T07:02:10.000Z",
      "ended_at": "2026-10-13T07:48:40.000Z",
      "duration_s": 2790,
      "dst": {
        "proto": "tcp",
        "ip": "10.20.0.15",
        "port": 445
      },
      "bytes_in": 18233411,
      "bytes_out": 902114,
      "end_reason": "closed",
      "reported_by": "cn0r4w8t2kq"
    }
  ],
  "by_app": [
    {
      "app": "Office LAN",
      "sessions": 1,
      "total_s": 2790
    }
  ],
  "probes_excluded": 4,
  "retention_days": 30,
  "note": "Sessions shorter than about 30 seconds may be missing. The exact address inside a private network is coming with the connector update."
}

List live sessions

GET/v0/tenants/{tenant_id}/sessions

read-only token

Returns every session open right now in your workspace: who is connected, from which device, to which app or private network, and through which Cloudraw edge. Cloudraw Connect's automatic reachability checks are left out. If live sessions cannot be read at the moment, overlay is unavailable and the list holds only portal-reported sessions — check that field before concluding nobody is connected.

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).
Example: tq7x2m9k4ab

Query parameters

connection_idstring
Only sessions to this app (connection). An unknown id returns an empty list.
Example: cx9m2v7d1pa
appstring
Only sessions to the app or private network with this exact name. Ignored when connection_id is sent.
Example: Finance RDP

Responses

200 The live sessions (not paginated).

application/json

itemsarray of LiveSessionrequired
items fields
- idstringrequired
  Session id. ovl_… = a live connection seen on the Cloudraw network right now (can be ended); ses_… = a session reported by the portal.
- sourcestringrequired
  overlay = observed live on the Cloudraw network; ingest = reported by the portal.
  One of: overlay, ingest.
- statestringrequired
  Always active in this list.
  One of: active.
- userstring | null
  Display name (or e-mail) of the person; for vendor access "<name> (<vendor>)"; for browser sessions the signed-in person, or "Browser user".
- devicestring | null
  Device name, Web browser (portal) for browser sessions, or vendor access.
- appstring | null
  Name of the app (connection) or private network being used.
- recordingboolean
  Whether this app records sessions.
- pathstring | null
  The Cloudraw edge nodes the session crosses, joined with " → ".
- edgestring | null
  The Cloudraw edge node the session entered through.
- lat_msinteger | null
  Latency in ms, when known.
- started_atstring | null (date-time)
  When the session started.
- kindstring
  Live sessions only: device = Cloudraw Connect or vendor access; browser = clientless browser access through the portal.
  One of: device, browser.
- connection_idstring | null
  Live sessions only: the app (connection) used.
- private_network_idstring | null
  Live sessions only: the private network used.
- device_idstring | null
  Live sessions only: the device.
- person_idstring | null
  Live sessions only: the person who owns the device or signed in to the portal.
- jit_grant_idstring | null
  Live sessions only: the just-in-time vendor grant, for vendor access.
- routersarray of string
  Live sessions only: the edge nodes on the path, in order.
- browserobject
  Browser sessions only.
  browser fields
  - launch_idstring | null
    The portal launch that opened this session.
  - ipstring | null
    The browser's public IP address.
  - viastring | null
    How it was launched (for example admin-test for a console test).
  - recording_idstring | null
    The recording of this session, if recorded.
counts_by_appobject
Active sessions per app name, over the whole workspace (filters do not apply).
overlaystringrequired
unavailable = live sessions could not be read right now; the list then holds only portal-reported sessions. It never silently comes back empty.
One of: ok, unavailable.
next_pagenull
Always null: the list is 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

curl -sS -X GET "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/sessions" \
  -H "Authorization: Bearer $CLOUDRAW_TOKEN"

PowerShell

$headers = @{ Authorization = "Bearer $env:CLOUDRAW_TOKEN" }
Invoke-RestMethod -Method Get -Uri "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/sessions" -Headers $headers

Python

import os, uuid, requests

r = requests.get(
    "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/sessions",
    headers={"Authorization": f"Bearer {os.environ['CLOUDRAW_TOKEN']}"},
    timeout=30,
)
r.raise_for_status()
print(r.json())

Node.js

const res = await fetch("https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/sessions", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CLOUDRAW_TOKEN}`,
  },
});
if (!res.ok) throw new Error((await res.json()).code);
console.log(await res.json());

Response 200 · application/json

{
  "items": [
    {
      "id": "ovl_7f3k9x2m0qd8s1a",
      "source": "overlay",
      "state": "active",
      "user": "Dana Levi",
      "device": "DANA-LAPTOP",
      "app": "Finance RDP",
      "recording": true,
      "path": "edge-1 → edge-3",
      "edge": "edge-1",
      "lat_ms": null,
      "started_at": "2026-10-13T08:51:40.000Z",
      "connection_id": "cx9m2v7d1pa",
      "private_network_id": null,
      "device_id": "dvc_5mxq2b7r8k",
      "person_id": "pz81kd03mna",
      "jit_grant_id": null,
      "routers": [
        "edge-1",
        "edge-3"
      ],
      "kind": "device"
    }
  ],
  "counts_by_app": {
    "Finance RDP": 1
  },
  "overlay": "ok",
  "next_page": null
}

End a session

DELETE/v0/tenants/{tenant_id}/sessions/{session_id}

full-access token

Cuts a live session immediately on the Cloudraw network. The device can reconnect at once if its access still allows it — to keep it out, also remove its access, quarantine the device or suspend the person. The action is written to the audit log (session.kill) with the reason and note you send. The body is optional; without it the reason is ADMIN_TERMINATED.

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).
Example: tq7x2m9k4ab
session_idstringrequired
Session id from GET …/sessions (ovl_… or ses_…).
Example: ovl_7f3k9x2m0qd8s1a

Request body application/json

reasonstring
Why the session is ended. Default ADMIN_TERMINATED.
One of: ADMIN_TERMINATED, SECURITY_INCIDENT, POLICY_REVOKED, REAUTH_REQUIRED, POSTURE_FAILED.
notestring
Free text for the audit log; longer text is cut at 300 characters.
Max length 300.

Responses

202 The session was ended (the task is already done).

application/json

idstringrequired
tenant_idstring
statestringrequired
One of: pending, running, done, failed.
result_uristring | null
errorobject | string | null
Why it failed, or a short status note (e.g. revoke_pending).

400 invalid-reason

invalid-reason: reason is not one of the listed codes.

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 session-not-found tenant-not-found

session-not-found: No active session with this id (it may have ended already).

tenant-not-found: No workspace with this id.

502 end-session-failed

end-session-failed: The session could not be ended right now. Retry.

503 busy

busy: Cloudraw is switching servers or cannot save right now. Retry after Retry-After seconds.

curl

curl -sS -X DELETE "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/sessions/ovl_7f3k9x2m0qd8s1a" \
  -H "Authorization: Bearer $CLOUDRAW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "SECURITY_INCIDENT",
  "note": "Laptop reported stolen"
}'

PowerShell

$body = @'
{
  "reason": "SECURITY_INCIDENT",
  "note": "Laptop reported stolen"
}
'@
$headers = @{ Authorization = "Bearer $env:CLOUDRAW_TOKEN" }
Invoke-RestMethod -Method Delete -Uri "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/sessions/ovl_7f3k9x2m0qd8s1a" -Headers $headers -ContentType "application/json" -Body $body

Python

import os, uuid, requests

r = requests.delete(
    "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/sessions/ovl_7f3k9x2m0qd8s1a",
    headers={"Authorization": f"Bearer {os.environ['CLOUDRAW_TOKEN']}"},
    json={
        "reason": "SECURITY_INCIDENT",
        "note": "Laptop reported stolen"
    },
    timeout=30,
)
r.raise_for_status()
print(r.status_code)

Node.js

const res = await fetch("https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/sessions/ovl_7f3k9x2m0qd8s1a", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.CLOUDRAW_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "reason": "SECURITY_INCIDENT",
    "note": "Laptop reported stolen"
  }),
});
if (!res.ok) throw new Error((await res.json()).code);
console.log(res.status);

Response 202 · application/json

{
  "id": "task_4k9x2m0s8d1q",
  "tenant_id": "tq7x2m9k4ab",
  "state": "done",
  "result_uri": null,
  "error": null
}