Provisioning & Lifecycle
When a tenant is created, the partner backend calls the Neon Create Project API to provision a dedicated project — typically in under a second — specifying the name, Postgres version, region, and initial compute and quota settings. Store the returned project ID, connection details, and record the tenant-to-project mapping in your own registry.
Every lifecycle step — create, configure, retrieve the connection string, suspend, restore, and delete — must be programmatic and idempotent, and must account for asynchronous operations.
Documentation: Create a project (Embedded Postgres) | Neon API reference
Which Credential Should You Use?
This is a deliberate design decision. It applies to every control-plane action — creating projects, setting quotas, retrieving connection strings, and reading usage — not just the initial provisioning. Neon offers three API key types:
| Credential | Scope | What Neon intends it for |
|---|---|---|
| Organization API key | All projects in the organization (admin-level access) | Team automation and CI/CD. |
| Project-scoped API key | Single project access | Limited-access to one project. |
| Personal API key | Projects the individual is a member of | Individual development and scripting. Not for production automation — it is tied to a person, not the partner's product. |
Org API key. The platform's central automation credential. Only the org key can perform these fleet-level actions:
- Create a tenant's project on signup (project-scoped keys cannot create projects).
- Delete a project on offboarding (a project-scoped key cannot delete its own project).
- List projects across the org for fleet inventory.
- Read org-level consumption for metering.
- Mint project-scoped API keys for individual projects.
Per-project changes — patching a project's compute or quota when a tenant changes plan, or suspending and restoring its compute — are usually done here too, because the central service already holds the org key. But they are not org-key-exclusive: a project-scoped key has Editor access and can make the same changes within its own project.
Project-Scoped API key. It holds Editor access on exactly one project, so it can read and modify everything inside that project but nothing outside it. Use it to:
- Give a customer's self-service surface — a key for that customer's project only.
- Give a support or debugging tool access to one tenant's project without exposing the rest of the fleet.
- Create branches, update compute, manage databases and roles for a project — for example, spin up a branch for a tenant's preview environment or reset a role's password.
- It cannot create or delete the project, manage who can access it, mint keys, or read any other project. It also stops working if the project is transferred out of the organization.
Recommendation: use an org API key as the platform's central automation credential — the projects belong to the partner's Neon organization, and only it can create them and read org-level usage. Where you need to delegate management of a single tenant's project to a per-tenant component, a support tool, or the tenant themselves, use the org key to provision a a project-scoped key for that project - so whatever holds it is confined to one tenant. Treat both as high-value secrets: store them in a managed secret store, scope and rotate them, and never expose them to the browser or the tenant.
Documentation: Manage API keys | API key types & authentication
Neon returns an API key's token only at creation and never again. Capture it into your secret store as part of the automated flow.
What's Next
- Compute, Scaling & Limits — Configure autoscaling and consumption quotas at creation
- Connectivity & Data Access — Retrieve the connection string and connect the application