Organizations
Your Layers org is the top-level account. It owns API keys, billing, and every project beneath it.
One partner, one organization. The org is the root of everything you do with the Partner API — it holds your API keys, it's the billing principal for credits and ads spend, and every project you create on behalf of a customer nests beneath it.
You don't create orgs through the API. Your org is provisioned when you're onboarded as a partner, and from that point forward every request you make resolves back to it.
How an org maps to your customers
One Layers org can host many projects. Each project represents a single end-customer. This is the intended shape:
your org ──┬── project A (customer "acme-prod")
├── project B (customer "wayne-labs")
└── project C (customer "stark-industries")There are no per-customer sub-orgs and no child API keys. A single org-scoped key can touch any project inside the org, and you keep your customers isolated from each other by path-scoping — every project-scoped route lives under /v1/projects/:projectId/... and the server refuses access to any project that doesn't belong to your org (with a 404 NOT_FOUND — we don't leak existence with a 403).
For belt-and-suspenders verification, read the project first via GET /v1/projects/:projectId and assert customerExternalId matches what your code thinks it should be before issuing follow-up calls.
What the org owns
| Resource | Notes |
|---|---|
| API keys | One or more per org. Scoped to the org, not to a project. |
| Projects | One per end-customer. Hard-archive is soft. |
| Credits | Content generation debits the org wallet. |
| Ads wallet | Ads spend debits the org wallet separately from credits. |
| Leased-account billing | Per-account monthly price set by Layers at assignment; surfaced as monthlyPriceCents on each account. Billed to the org wallet on renewal. |
| Audit log | Every write is stamped with (api_key_id, org_id, project_id). |
Introspecting your org
The first call any client makes is GET /v1/whoami. It resolves your key to the org it belongs to, echoes your organization name, names your rate-limit tier, and tells you whether the org-wide kill switch is flipped. If killSwitch or apiAccessRevoked is true, every other call fails with 503 KILL_SWITCH until cleared — call /whoami first so you know before you try.