Organizations and projects
Four things, and none of them is the same as another. Getting the shape right early is what stops a leaked key being an account-wide problem.
account ──owns──▶ organization ──holds──▶ project ──issues──▶ API key
(a person) (a tenant) (a workload) (a credential)Why they are separate
An account is a person
One email, one password, one set of sessions. It is who you are, and it is not a thing that gets billed, scoped or shared.
An organization is a tenant
Projects belong to an organization rather than to a person, so they outlive one account and can be shared later without moving anything. Deleting a person does not delete the work.
A project is a workload
One project is one thing you are building: a wallet, a checkout, a reconciliation job. It carries its own allowed networks, its own capability scope, its own quota and its own rate limit.
This is the isolation unit. A project at its ceiling is refused; every other project’s state is untouched. If two workloads should not be able to exhaust each other, they are two projects.
An API key is a credential
A key belongs to exactly one project and can never reach more than that project was given. Several keys per project is normal — one per deployment, one per environment — because revoking one then costs you one deployment rather than all of them.
Environments
A project is TEST or PRODUCTION, and this is not a
label. A key scoped to TEST cannot reach PRODUCTION, and
the separation is enforced rather than conventional.
On this deployment PRODUCTION is unavailable,
because it requires a proved email address and no mail provider is configured
here. TEST projects carry the same read capabilities, so nothing
about the API is different; what differs is the authority behind it.
Choosing a shape
One project per workload, not per customer. A project is where a quota lives. Splitting per customer means splitting your quota per customer, which is almost never what you want.
One key per deployment. Staging and production of the same workload are two keys on one project, so a rotation in one does not touch the other.
Scope narrowly. A project that only reads Base should not be allowed Polygon. The refusal is instant and the blast radius of a leak is whatever you allowed.
Two organizations is for two tenants, not two environments. Environments are a field on a project.
Limits
Every one of these has a Beta limit, and each one says which measurement it came from. See Limits.