Guide

Getting started

Create an API token in the console, then make your first call. About two minutes.

Create a token. In the Cloudraw console open Settings → API and choose Create token. Give it a name that says what uses it (for example hr-sync), pick Read-only to start, and an expiry (default 90 days). Only a workspace owner or security admin can create tokens; only an owner can create a full-access token.
Copy it now. The token (crw_…) is shown once. Store it in your secret manager or CI secret store — never in source code. If you lose it, revoke it and create a new one.
Find your workspace id. It is on the same page (and in every console URL). In these docs it looks like tq7x2m9k4ab.
Make a call. Read your workspace:

curl

export CLOUDRAW_TOKEN="crw_…"          # from your secret store
export CLOUDRAW_TENANT="tq7x2m9k4ab"

curl -sS "https://cdapi.cloudraw.com/v0/tenants/$CLOUDRAW_TENANT" \
  -H "Authorization: Bearer $CLOUDRAW_TOKEN"

PowerShell

$env:CLOUDRAW_TOKEN = "crw_…"          # from your secret store
$tenant = "tq7x2m9k4ab"

Invoke-RestMethod -Uri "https://cdapi.cloudraw.com/v0/tenants/$tenant" `
  -Headers @{ Authorization = "Bearer $env:CLOUDRAW_TOKEN" }

Python

import os, requests

BASE = "https://cdapi.cloudraw.com"
TENANT = "tq7x2m9k4ab"
s = requests.Session()
s.headers["Authorization"] = f"Bearer {os.environ['CLOUDRAW_TOKEN']}"

r = s.get(f"{BASE}/v0/tenants/{TENANT}", timeout=30)
r.raise_for_status()
print(r.json()["name"])

Node.js

// Node 18+ (built-in fetch)
const BASE = "https://cdapi.cloudraw.com";
const TENANT = "tq7x2m9k4ab";

const res = await fetch(`${BASE}/v0/tenants/${TENANT}`, {
  headers: { Authorization: `Bearer ${process.env.CLOUDRAW_TOKEN}` },
});
if (!res.ok) throw new Error((await res.json()).code);
console.log((await res.json()).name);

You get your workspace back:

{
  "id": "tq7x2m9k4ab",
  "name": "Northwind Logistics",
  "usage": { "users": 18, "devices": 23, "connections": 7, "connectors": 2, "private_networks": 1 },
  "version": 42,
  …
}

Next: list the people in the workspace

curl

curl -sS "https://cdapi.cloudraw.com/v0/tenants/$CLOUDRAW_TENANT/people" \
  -H "Authorization: Bearer $CLOUDRAW_TOKEN"

PowerShell

(Invoke-RestMethod -Uri "https://cdapi.cloudraw.com/v0/tenants/$tenant/people" `
  -Headers @{ Authorization = "Bearer $env:CLOUDRAW_TOKEN" }).items |
  Select-Object email, name, groups

Python

people = s.get(f"{BASE}/v0/tenants/{TENANT}/people", timeout=30).json()["items"]
for p in people:
    print(p["email"], p["groups"])

Node.js

const r = await fetch(`${BASE}/v0/tenants/${TENANT}/people`, {
  headers: { Authorization: `Bearer ${process.env.CLOUDRAW_TOKEN}` },
});
for (const p of (await r.json()).items) console.log(p.email, p.groups);

Making changes

A read-only token gets 403 insufficient-scope on anything that changes data. For changes, an owner creates a full-access token. Send an Idempotency-Key with every POST so a retry after a network error never does the work twice:

curl

curl -sS -X POST "https://cdapi.cloudraw.com/v0/tenants/$CLOUDRAW_TENANT/people" \
  -H "Authorization: Bearer $CLOUDRAW_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"email": "dana.levi@example.com", "name": "Dana Levi"}'

PowerShell

$body = @{ email = "dana.levi@example.com"; name = "Dana Levi" } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri "https://cdapi.cloudraw.com/v0/tenants/$tenant/people" `
  -Headers @{ Authorization = "Bearer $env:CLOUDRAW_TOKEN"; "Idempotency-Key" = [guid]::NewGuid().ToString() } `
  -ContentType "application/json" -Body $body

Python

import uuid
r = s.post(f"{BASE}/v0/tenants/{TENANT}/people",
           json={"email": "dana.levi@example.com", "name": "Dana Levi"},
           headers={"Idempotency-Key": str(uuid.uuid4())}, timeout=30)
r.raise_for_status()

Node.js

await fetch(`${BASE}/v0/tenants/${TENANT}/people`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CLOUDRAW_TOKEN}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "dana.levi@example.com", name: "Dana Levi" }),
});

Every change made with a token is in the audit log, attributed to the token (token:<name>).

Where next

API reference — every operation with samples.
Errors — the code values to switch on.
Webhooks — get alerts pushed to you instead of polling.