Authentication
Every request to api.insuredaudit.com/v1 requires an API key passed as an HTTP Authorization header:
Authorization: Bearer ck_live_abc123...API key model
- Tenant-scoped. A key only authorizes operations on its issuing tenant. Cross-tenant operations are impossible by construction.
- Scope-limited. Each key carries a set of scopes (e.g.
events:write,bundles:export). A request that needs a scope the key lacks returns403 FORBIDDEN. - Hashed at rest. Only an Argon2 hash is stored server-side; the secret can’t be retrieved after creation. Lost keys must be rotated.
- Revocable.
DELETE /v1/api-keys/{id}permanently removes a key; existing in-flight requests still complete.
Scope reference
| Scope | Grants |
|---|---|
events:read | Search + read events, member timelines, dashboard counts. |
events:write | POST /v1/events, /v1/events/validate. |
documents:read | GET document metadata + bytes. |
documents:write | POST /v1/documents, redactions. |
bundles:request | POST /v1/bundles, regenerate. |
bundles:read | List + inspect bundles, diff, verify-signature. |
bundles:export | Download sealed bundle ZIP / eDX export. |
rules:read / rules:write | Rule corpus list / ingest. |
legal-holds:read / legal-holds:write | Hold management. |
legal-matters:read / legal-matters:write | Matter management. |
exceptions:read / exceptions:write | Operator exception queue. |
feeds:read / feeds:write | Source feed monitor. |
custody:read | Chain-of-custody log. |
graph:read | Event graph queries. |
connectors:write | Adapter connector lifecycle. |
signing-keys:read / signing-keys:write | Bundle signing keys. |
search:read | Full-text search. |
ai-provenance:write | POST AI decision provenance. |
admin | Tenant + actor + role administration, webhook CRUD, quarantine release. |
Tenant resolution
Routes that target a tenant accept tenant_id on the query string, or via the X-Tenant-Id header. If the SDK was constructed with a default tenantId, every request gets it automatically.
Rate limits
Limits are enforced per (tenant, route family) and surface as 429 RATE_LIMITED with a Retry-After header. Default budgets:
POST /v1/events: 600 envelopes/min (batches count toward this).POST /v1/documents: 120 uploads/min.- All other write routes: 300 req/min.
- Read routes: 1200 req/min.
Operators can lift caps per-tenant by editing tenant.rate_limit_overrides_json.
Authentication errors
| Status | Code | Cause |
|---|---|---|
| 401 | UNAUTHENTICATED | Header missing or malformed. |
| 401 | INVALID_KEY | Key not found or revoked. |
| 403 | FORBIDDEN | Key lacks the required scope. |
| 429 | RATE_LIMITED | Per-tenant budget exceeded. |