> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Organizations

## Worked organizations samples

The endpoint list below documents every operation's parameters; this
overlay walks the two operations a billing-conscious integration actually
uses: **read the monthly SLA report → read any owed SLA credit → mint the
re-auth challenge when the caller needs the irreversible DELETE**. Success
envelopes are `{ data, meta }`, error envelopes `{ error, meta }` — see
[How to read a worked sample](/guides/using-orbit-samples). Every request
uses your tenant-scoped API key (`X-API-Key`); the SLA report is an
org-admin read, and the re-auth challenge is owner-only by design.

Every response carries `meta.request_id`. Quote the request id when you
report a miscalculated window or a re-auth the DELETE route rejects — a
support trace needs both the window and the 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`.

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```

  ```typescript Node.js theme={null}
  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());
  ```
</CodeGroup>

```json 200 theme={null}
{
  "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.

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```

  ```typescript Node.js theme={null}
  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());
  ```
</CodeGroup>

```json 200 theme={null}
{
  "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.

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```

  ```typescript Node.js theme={null}
  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());
  ```
</CodeGroup>

```json 200 theme={null}
{
  "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. Errors

Errors follow the `{ error, meta }` envelope. Two failures every caller
must handle:

**403 — id is not the caller's own organization.** The endpoint returns
this before minting, so a token stolen from a session cannot mint a token
for someone else's workspace.

```json 403 theme={null}
{
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "The re-auth challenge can only be minted for your own organization.",
    "status": 403
  },
  "meta": {
    "request_id": "req_org_err",
    "timestamp": "2026-09-01T06:00:03.000Z"
  }
}
```

**409 — idempotency key in flight.** The same `Idempotency-Key` fired
concurrently; wait for the in-flight request to land before retrying.

```json 409 theme={null}
{
  "error": {
    "code": "IDEMPOTENCY_CONFLICT",
    "message": "An identical request with this Idempotency-Key is still in flight.",
    "status": 409
  },
  "meta": {
    "request_id": "req_org_err2",
    "timestamp": "2026-09-01T06:00:04.000Z"
  }
}
```