{"openapi":"3.0.3","info":{"title":"Organizations (Multi-Tenancy) API","version":"1.0.0","description":"# Organizations — Tenancy & Agency Fleet Management\n\nAn **Organization** is a tenant on NowLanguage: a language agency,\nenterprise partner, or reseller that brings its own interpreters and\ncustomers and runs them on NowLanguage's session engine.\n\nTenancy is **additive and nullable** — resources without an\n`organization` reference belong to the NowLanguage platform marketplace.\nNothing about existing users/sessions changes until they join an org.\n\n## How the pieces compose\n\n| Entity | Field | Meaning |\n|--------|-------|---------|\n| `Organization` | — | The tenant: name, slug, branding, limits, owner |\n| `User.organization` | + `organizationRole` | A person in the org roster (`owner`, `admin`, `dispatcher`, `interpreter`, `member`) |\n| `ApiKey.organization` | — | Org-scoped developer key: everything it creates/reads is confined to the org |\n| `Work_Session.organization_id` | — | Which tenant a session belongs to |\n\n## Two ways in\n\n1. **Org dashboard APIs** (this document) — JWT-authenticated org\n   management: roster, sessions, stats. Used by agency staff in the app.\n2. **Org-scoped API keys** (`/v1/*`) — attach an `organization` to an\n   `nl_live_`/`nl_test_` key and every session it creates is stamped\n   `organization_id`; `GET /v1/sessions` returns only that org's\n   sessions; `GET /v1/interpreters/available` returns the org roster.\n   An agency embedding NowLanguage gets fleet behavior through the API.\n\n## Roles\n\n- `owner` — full control incl. billing/status (created with the org)\n- `admin` — manage members, settings, sessions\n- `dispatcher` — ops role, assign/manage sessions (read-mostly today)\n- `interpreter` — the org's labor roster; appears in org interpreter queries\n- `member` — generic member\n\n## Scoping rules\n\n- Org keys (`ApiKey.organization` set): sessions/interpreters visible = **org only**\n- Platform keys (no org): sessions created by the **key's owning user**\n- JWT routes: members read their org; `owner`/`admin`/platform-`admin` write\n"},"tags":[{"name":"Organizations","description":"Multi-tenant org management (JWT auth)"}],"paths":{"/api/organizations":{"post":{"summary":"Create an organization","tags":["Organizations"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"Acme Interpreting"},"slug":{"type":"string","example":"acme-interpreting","description":"auto-generated from name if omitted"},"type":{"type":"string","enum":["agency","enterprise","partner","reseller"],"default":"agency"},"billingEmail":{"type":"string","format":"email"},"branding":{"type":"object","properties":{"displayName":{"type":"string"},"logoUrl":{"type":"string"},"primaryColor":{"type":"string"},"supportEmail":{"type":"string"},"domain":{"type":"string"}}},"settings":{"type":"object","properties":{"timezone":{"type":"string","example":"America/Chicago"},"defaultServiceType":{"type":"string","enum":["video","audio","in_person","chat"]},"preferOwnInterpreters":{"type":"boolean","default":true}}}}}}}},"responses":{"201":{"description":"Organization created; creator attached as owner"},"400":{"description":"Missing name"}}}},"/api/organizations/mine":{"get":{"summary":"List my organizations","tags":["Organizations"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Orgs I own or belong to"}}}},"/api/organizations/{id}":{"get":{"summary":"Get organization detail","tags":["Organizations"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Organization + my membership role"},"403":{"description":"Not a member"},"404":{"description":"Not found"}}},"patch":{"summary":"Update organization (owner/admin)","tags":["Organizations"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"branding":{"type":"object"},"settings":{"type":"object"},"limits":{"type":"object"},"status":{"type":"string","enum":["active","trialing","suspended","closed"]}}}}}},"responses":{"200":{"description":"Updated org"},"403":{"description":"Admin role required"}}}},"/api/organizations/{id}/members":{"get":{"summary":"List org roster","tags":["Organizations"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Members with roles + language services"}}},"post":{"summary":"Add member by email (owner/admin)","tags":["Organizations"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","description":"must already have a NowLanguage account"},"role":{"type":"string","enum":["admin","dispatcher","interpreter","member"],"default":"interpreter"}}}}}},"responses":{"200":{"description":"Member added"},"402":{"description":"Member limit reached"},"404":{"description":"User not found — invite them to sign up first"},"409":{"description":"User belongs to another org"}}}},"/api/organizations/{id}/members/{userId}":{"patch":{"summary":"Change member role","tags":["Organizations"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"path","name":"userId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["role"],"properties":{"role":{"type":"string","enum":["admin","dispatcher","interpreter","member"]}}}}}},"responses":{"200":{"description":"Role updated"}}},"delete":{"summary":"Remove member","tags":["Organizations"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"path","name":"userId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Removed"},"400":{"description":"Cannot remove owner"}}}},"/api/organizations/{id}/sessions":{"get":{"summary":"Org sessions (tenant-scoped list)","tags":["Organizations"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"query","name":"status","schema":{"type":"string","example":"Pending"}},{"in":"query","name":"limit","schema":{"type":"integer","maximum":100,"default":50}},{"in":"query","name":"skip","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Sessions where organization_id = org"}}}},"/api/organizations/{id}/stats":{"get":{"summary":"Org ops stats (roster + sessions by status)","tags":["Organizations"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"```json\n{ \"stats\": { \"members\": 12, \"interpreters\": 9,\n             \"sessionsByStatus\": { \"Pending\": 3, \"Completed\": 41 },\n             \"totalSessions\": 44 } }\n```\n"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}}}}