Organizations

Worked organizations samples

The endpoint list below documents every operation’s parameters; this overlay walks the complete lifecycle a billing-conscious integration uses: read the monthly SLA report → read any owed SLA credit → mint the re-auth challenge → delete the workspace. Success envelopes are { data, meta }, error envelopes { error, meta } — see How to read a worked sample. Every request uses your tenant-scoped API key (X-API-Key); the SLA report is an org-admin read, and workspace destruction is owner-only by design. Organization bodies carry id, name, plan, seat_limit, and created_at. Create and update run through the auth provider (Clerk) mirror; this page owns the org-scoped lifecycle verbs — SLA reads plus the owner-only workspace-deletion gate. Responses below show the concrete { data, meta } shape the API returns for each of the four routes on this page. Every response carries meta.request_id. Quote the request id when you report a miscalculated window, an SLA credit dispute, or a workspace deletion the re-auth gate refused — a support trace needs the window and the challenge token id.

1. Read the monthly SLA report

GET /api/v1/organizations/sla-report returns, for one ?period=YYYY-MM calendar month, the per-channel availability percentage, the public incident windows that affected the tenant’s channels, and the tenant’s per-channel delivery success rate over the period. The report is a pure read-model over the public incident feed and the messages time-series — the same inputs always produce the same report. Exportable as CSV with ?format=csv.

curl -X GET \
  "https://api.orbit.devotel.io/api/v1/organizations/sla-report?period=2026-08" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/organizations/sla-report?period=2026-08",
  {
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  },
);
console.log(await res.json());

import os, requests

r = requests.get(
    "https://api.orbit.devotel.io/api/v1/organizations/sla-report?period=2026-08",
    headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
)
print(r.json())

200

{
  "data": {
    "period": "2026-08",
    "channels": [
      {
        "channel": "sms",
        "availability_percent": 99.94,
        "incident_minutes": 26,
        "delivery_success_rate": 0.986
      }
    ],
    "incidents": [
      {
        "id": "inc_8fb2d1b7c00c4ec9",
        "title": "SMS delivery degradation — Gateway A",
        "status": "resolved",
        "impact": "minor",
        "affected_components": ["sms"],
        "started_at": "2026-08-12T07:42:00.000Z",
        "resolved_at": "2026-08-12T08:08:00.000Z"
      }
    ]
  },
  "meta": {
    "request_id": "req_org_sla",
    "timestamp": "2026-09-01T06:00:00.000Z"
  }
}

availability_percent is per-channel — the month minutes minus the overlapping incident minutes, pro-rated across the month boundary.
The same inputs always produce the same output, so the CSV export is a straight-through snapshot of the same report. Use ?format=csv to export.

2. Read any owed SLA credit

GET /api/v1/organizations/sla-report/credit applies the published SLA credit schedule to the same report — the minutes the platform missed its availability commitment and the corresponding owed percentage. When no schedule applies, the returned object reports no credit.

curl -X GET \
  "https://api.orbit.devotel.io/api/v1/organizations/sla-report/credit?period=2026-08" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/organizations/sla-report/credit?period=2026-08",
  {
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  },
);
console.log(await res.json());

200

{
  "data": {
    "period": "2026-08",
    "channel": "sms",
    "availability_percent": 99.94,
    "credit_percent": 0,
    "credit_amount_usd": 0
  },
  "meta": {
    "request_id": "req_org_slacredit",
    "timestamp": "2026-09-01T06:00:01.000Z"
  }
}

3. Mint the workspace-deletion re-auth challenge

POST /api/v1/organizations/{id}/reauth-challenge mints a five-minute, single-use token scoped to workspace_delete:<id> for the calling owner’s organization. The irreversible landlord-scoped DELETE rejects any hold that was not minted through this endpoint in the last five minutes. Takes no request body; owner-only, audit-logged, idempotent via the Idempotency-Key header. Returns 403 when the id is not the caller’s own organization and 401 when the session has no authenticated user.

curl -X POST \
  "https://api.orbit.devotel.io/api/v1/organizations/org_8fb2d1b7c00c4ec9/reauth-challenge" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Idempotency-Key: ws-delete-reauth-2026-09-01-0001"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/organizations/org_8fb2d1b7c00c4ec9/reauth-challenge",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_API_KEY!,
      "Idempotency-Key": "ws-delete-reauth-2026-09-01-0001",
    },
  },
);
console.log(await res.json());

200

{
  "data": {
    "reauth_challenge": "wrc_9e8d7c6b5a4f3021",
    "scope": "workspace_delete:org_8fb2d1b7c00c4ec9",
    "expires_at": "2026-09-01T06:05:00.000Z"
  },
  "meta": {
    "request_id": "req_org_reauth",
    "timestamp": "2026-09-01T06:00:02.000Z"
  }
}

The token is single-use — a successful DELETE /organizations/:id consumes it and the next destruction needs a fresh mint.

4. Delete the workspace (owner-only)

DELETE /api/v1/organizations/{id} runs the local cleanup cascade and Clerk mirror after a member-consistency check. Body must be { confirm: "DELETE" } and the X-Reauth-Challenge header must carry a token minted in the last five minutes (step 3). Owner-only; returns 202 once the cascade is accepted.

curl -X DELETE \
  "https://api.orbit.devotel.io/api/v1/organizations/org_8fb2d1b7c00c4ec9" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "X-Reauth-Challenge: wrc_9e8d7c6b5a4f3021" \
  -H "Content-Type: application/json" \
  -d '{"confirm": "DELETE"}'

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/organizations/org_8fb2d1b7c00c4ec9",
  {
    method: "DELETE",
    headers: {
      "X-API-Key": process.env.ORBIT_API_KEY!,
      "X-Reauth-Challenge": "wrc_9e8d7c6b5a4f3021",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ confirm: "DELETE" }),
  },
);
console.log(await res.json());

202

{
  "data": {
    "message": "Workspace deletion in progress. All data will be removed within ~1 minute."
  },
  "meta": {
    "request_id": "req_org_delete",
    "timestamp": "2026-09-01T06:01:00.000Z"
  }
}

5. Errors

Errors follow the { error, meta } envelope. Three failures every caller must handle: 403 — permission gate. The endpoint returns this before minting or deleting when the id is not the caller’s own organization, or when the caller lacks the owner role. A stolen session cannot mint a token for someone else’s workspace.

403

{
  "error": {
    "code": "FORBIDDEN",
    "message": "You can only delete your own workspace.",
    "status": 403
  },
  "meta": {
    "request_id": "req_org_err",
    "timestamp": "2026-09-01T06:00:03.000Z"
  }
}

401 — stale or missing re-auth challenge. The delete route rejects a challenge token that was not minted in the last five minutes, or a request whose session has no authenticated user. Mint a fresh challenge and retry.

401

{
  "error": {
    "code": "REAUTH_REQUIRED",
    "message": "Fresh re-authentication is required for workspace deletion.",
    "status": 401
  },
  "meta": {
    "request_id": "req_org_err2",
    "timestamp": "2026-09-01T06:00:04.000Z"
  }
}

409 — already deleted. Re-deleting a workspace that has already run its cascade is a conflict, not a no-op.

409

{
  "error": {
    "code": "ALREADY_DELETED",
    "message": "This workspace has already been deleted.",
    "status": 409
  },
  "meta": {
    "request_id": "req_org_err3",
    "timestamp": "2026-09-01T06:00:05.000Z"
  }
}

API Reference

All Endpoints

Worked organizations samples

1. Read the monthly SLA report

2. Read any owed SLA credit

3. Mint the workspace-deletion re-auth challenge

4. Delete the workspace (owner-only)

5. Errors

​Worked organizations samples

​1. Read the monthly SLA report

​2. Read any owed SLA credit

​3. Mint the workspace-deletion re-auth challenge

​4. Delete the workspace (owner-only)

​5. Errors

Worked organizations samples

1. Read the monthly SLA report

2. Read any owed SLA credit

3. Mint the workspace-deletion re-auth challenge

4. Delete the workspace (owner-only)

5. Errors