API reference

Groups

Groups of people. Access rules and apps are usually granted to groups.

GETList groups
POSTCreate a group
GETGet a group
PATCHUpdate a group
DELETEDelete a group

List groups

GET/v0/tenants/{tenant_id}/groups

read-only token

Returns every group in the workspace — created in Cloudraw, imported from Active Directory, or synced by your directory — with its members and how many rules use it. Not paginated; sorted by name.

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

Responses

200 All groups.

application/json

itemsarray of GroupListItemrequired
directory_sourcestring | null
The connected directory, if any.
One of: ad, scim, .

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/groups" \
  -H "Authorization: Bearer $CLOUDRAW_TOKEN"

PowerShell

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

Python

import os, uuid, requests

r = requests.get(
    "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/groups",
    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/groups", {
  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": "g3k9d0s7aa",
      "display_name": "Finance",
      "source": "local",
      "member_count": 2,
      "members": [
        {
          "id": "pz81kd03mna",
          "name": "Dana Levi",
          "email": "dana.levi@example.com"
        },
        {
          "id": "p4hd8s0qk2l",
          "name": "Omer Katz",
          "email": "omer.katz@example.com"
        }
      ],
      "created_at": "2026-09-21T10:00:00.000Z",
      "updated_at": "2026-10-13T09:24:11.000Z",
      "used_by_rules": 2
    }
  ],
  "directory_source": null
}

Create a group

POST/v0/tenants/{tenant_id}/groups

full-access token

Creates a group managed in Cloudraw (source: local), optionally with members. Members' devices get the group's access at once. Use the group in access rules to grant it apps or networks. 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).
Example: tq7x2m9k4ab

Request body application/json

namestringrequired
Name, 1-80 characters, no control characters or < >. Unique in the workspace (case-insensitive). display_name is accepted as an alias.
membersarray of string
Person ids (up to 500); each must exist.

Responses

201 The new group.

application/json

idstringrequired
Group id.
display_namestringrequired
Name, 1-80 characters, unique in the workspace (case-insensitive).
sourcestringrequired
local = created in Cloudraw (editable here); ad = imported from Active Directory; scim / directory = managed by your directory.
One of: local, ad, scim, directory.
dnstring
Only for ad groups: the distinguished name in Active Directory.
member_countintegerrequired
membersarray of objectrequired
members fields
- idstring
- namestring | null
- emailstring | null
created_atstring | null (date-time)
updated_atstring | null (date-time)

400 invalid-name unknown-people

invalid-name: The name is missing, longer than 80 characters or contains a forbidden character.

unknown-people: Some members are not people in this workspace.

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

group-exists: A group with this name already exists.

503 busy

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

curl

curl -sS -X POST "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/groups" \
  -H "Authorization: Bearer $CLOUDRAW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Finance",
  "members": [
    "pz81kd03mna",
    "p4hd8s0qk2l"
  ]
}'

PowerShell

$body = @'
{
  "name": "Finance",
  "members": [
    "pz81kd03mna",
    "p4hd8s0qk2l"
  ]
}
'@
$headers = @{ Authorization = "Bearer $env:CLOUDRAW_TOKEN" }
Invoke-RestMethod -Method Post -Uri "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/groups" -Headers $headers -ContentType "application/json" -Body $body

Python

import os, uuid, requests

r = requests.post(
    "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/groups",
    headers={"Authorization": f"Bearer {os.environ['CLOUDRAW_TOKEN']}"},
    json={
        "name": "Finance",
        "members": [
            "pz81kd03mna",
            "p4hd8s0qk2l"
        ]
    },
    timeout=30,
)
r.raise_for_status()
print(r.json())

Node.js

const res = await fetch("https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/groups", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CLOUDRAW_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Finance",
    "members": [
      "pz81kd03mna",
      "p4hd8s0qk2l"
    ]
  }),
});
if (!res.ok) throw new Error((await res.json()).code);
console.log(await res.json());

Response 201 · application/json

{
  "id": "g3k9d0s7aa",
  "display_name": "Finance",
  "source": "local",
  "member_count": 2,
  "members": [
    {
      "id": "pz81kd03mna",
      "name": "Dana Levi",
      "email": "dana.levi@example.com"
    },
    {
      "id": "p4hd8s0qk2l",
      "name": "Omer Katz",
      "email": "omer.katz@example.com"
    }
  ],
  "created_at": "2026-09-21T10:00:00.000Z",
  "updated_at": "2026-09-21T10:00:00.000Z"
}

Get a group

GET/v0/tenants/{tenant_id}/groups/{group_id}

read-only token

Returns one group with its members and the access and trust rules that use it.

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
group_idstringrequired
Group id (from List groups).
Example: g3k9d0s7aa

Responses

200 The group.

application/json

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

group-not-found: No group with this id (or it was deleted).

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

curl

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

PowerShell

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

Python

import os, uuid, requests

r = requests.get(
    "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/groups/g3k9d0s7aa",
    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/groups/g3k9d0s7aa", {
  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

{
  "id": "g3k9d0s7aa",
  "display_name": "Finance",
  "source": "local",
  "member_count": 2,
  "members": [
    {
      "id": "pz81kd03mna",
      "name": "Dana Levi",
      "email": "dana.levi@example.com"
    },
    {
      "id": "p4hd8s0qk2l",
      "name": "Omer Katz",
      "email": "omer.katz@example.com"
    }
  ],
  "created_at": "2026-09-21T10:00:00.000Z",
  "updated_at": "2026-10-13T09:24:11.000Z",
  "used_by_rules": [
    {
      "id": "pr_7xk2m9c0d1",
      "name": "Finance to ERP"
    },
    {
      "id": "tr_4m8s2k0x9q",
      "name": "Finance laptops",
      "kind": "trust"
    }
  ]
}

Update a group

PATCH/v0/tenants/{tenant_id}/groups/{group_id}

full-access token

Renames a group and/or adds and removes members. Only groups created in Cloudraw (source: local) can be changed; directory groups are changed in your directory. Members' device access is recalculated at once. Ids in remove that are not members are ignored. 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).
Example: tq7x2m9k4ab
group_idstringrequired
Group id (from List groups).
Example: g3k9d0s7aa

Request body application/json

namestring
New name (same rules as on create). display_name is accepted as an alias.
addarray of string
Person ids to add (up to 500); each must exist.
removearray of string
Person ids to remove (up to 500).

Responses

200 The updated group.

application/json

idstringrequired
Group id.
display_namestringrequired
Name, 1-80 characters, unique in the workspace (case-insensitive).
sourcestringrequired
local = created in Cloudraw (editable here); ad = imported from Active Directory; scim / directory = managed by your directory.
One of: local, ad, scim, directory.
dnstring
Only for ad groups: the distinguished name in Active Directory.
member_countintegerrequired
membersarray of objectrequired
members fields
- idstring
- namestring | null
- emailstring | null
created_atstring | null (date-time)
updated_atstring | null (date-time)

400 invalid-name unknown-people

invalid-name: The new name is empty, longer than 80 characters or contains a forbidden character.

unknown-people: Some ids in add are not people in this workspace.

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

group-not-found: No group with this id (or it was deleted).

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

409 group-managed-elsewhere group-exists

group-managed-elsewhere: The group comes from your directory; change it there.

group-exists: Another group already has this name.

503 busy

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

curl

curl -sS -X PATCH "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/groups/g3k9d0s7aa" \
  -H "Authorization: Bearer $CLOUDRAW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "add": [
    "p4hd8s0qk2l"
  ],
  "remove": []
}'

PowerShell

$body = @'
{
  "add": [
    "p4hd8s0qk2l"
  ],
  "remove": []
}
'@
$headers = @{ Authorization = "Bearer $env:CLOUDRAW_TOKEN" }
Invoke-RestMethod -Method Patch -Uri "https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/groups/g3k9d0s7aa" -Headers $headers -ContentType "application/json" -Body $body

Python

import os, uuid, requests

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

Node.js

const res = await fetch("https://cdapi.cloudraw.com/v0/tenants/tq7x2m9k4ab/groups/g3k9d0s7aa", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.CLOUDRAW_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "add": [
      "p4hd8s0qk2l"
    ],
    "remove": []
  }),
});
if (!res.ok) throw new Error((await res.json()).code);
console.log(await res.json());

Response 200 · application/json

{
  "id": "g3k9d0s7aa",
  "display_name": "Finance",
  "source": "local",
  "member_count": 2,
  "members": [
    {
      "id": "pz81kd03mna",
      "name": "Dana Levi",
      "email": "dana.levi@example.com"
    },
    {
      "id": "p4hd8s0qk2l",
      "name": "Omer Katz",
      "email": "omer.katz@example.com"
    }
  ],
  "created_at": "2026-09-21T10:00:00.000Z",
  "updated_at": "2026-10-13T09:24:11.000Z"
}

Delete a group

DELETE/v0/tenants/{tenant_id}/groups/{group_id}

full-access token

Deletes a group created in Cloudraw, or un-imports an Active Directory group (the group in Active Directory is not touched). Its members lose the access it gave. Refused while any access or trust rule still uses the group: remove it from those rules first. Groups synced by SCIM or another directory are removed there. 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).
Example: tq7x2m9k4ab
group_idstringrequired
Group id (from List groups).
Example: g3k9d0s7aa

Responses

204 Deleted.

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

group-not-found: No group with this id (or it was deleted).

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

409 group-managed-elsewhere group-in-use

group-managed-elsewhere: The group is managed by your directory; remove it there.

group-in-use: Rules still use this group; the problem body lists them in rules.

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/groups/g3k9d0s7aa" \
  -H "Authorization: Bearer $CLOUDRAW_TOKEN"

PowerShell

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

Python

import os, uuid, requests

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

Node.js

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