# Orita Multi-Organization Platforms

Tested with: Orita API v2
Last verified: 2026-07-31

Orita supports a two-level hierarchy:

```
Platform account
  → downstream organization
    → provider network
    → providers and services
    → resolution candidates
    → bookings
    → webhooks
```

## Create a downstream organization

POST /api/v2/organizations (requires platform key)

```json
{
  "externalId": "customer-org-abc",
  "name": "Nova Health",
  "settings": {}
}
```

## API key types

| Key type            | Can create orgs | Can operate across orgs         |
|---------------------|----------------|--------------------------------|
| platform_live       | Yes            | Yes, with Orita-Organization-Id header |
| platform_test       | Yes            | Yes, with Orita-Organization-Id header |
| organization_live   | No             | No — scoped to one org         |
| organization_test   | No             | No — scoped to one org         |

## Platform key cross-org operation

```
POST /api/v2/resolutions
Authorization: Bearer orita_platform_***
Orita-Organization-Id: org_01K...
```

The resolution is scoped to the downstream org.
Providing Orita-Organization-Id on an organization-scoped key returns 401.

## Tenant isolation guarantees

- Every table includes organization_id and platform_id
- Resolution candidates, holds, bookings, and webhooks are org-scoped
- Cross-tenant access returns 403 FORBIDDEN
- Audit events record every cross-org operation

## Audit log

GET /api/v2/audit-events

Immutable record of all write operations:
actor, action, resource_type, resource_id, request_id, before/after summary, timestamp.

## Machine-readable

- Capabilities: /capabilities.json
- OpenAPI: /openapi.json