Accounts, Tokens, and Scopes

In the user-facing SPG99 model, there are several basic entities, and almost all of them are managed through the Control Plane.

Account

An account is the top-level customer entity. It is associated with:

• contact data;
• API keys;
• tenants;
• usage for part of billing.

Accounts are convenient for separating teams, projects, or customers within one platform.

API key

An API key is a Bearer token for calling the Control Plane API. It is required for Console, automation, CLI, and REST calls, but it is not used as a PostgreSQL password.

A token has:

• a scope;
• permissions;
• an optional expiration time.

Three main scopes are supported:

• global — the broadest administrative access;
• account — access to one account and its resources;
• tenant — access to only one tenant.

Permissions are configured separately. Most often, the user sees these flags:

• can_create_tenant;
• can_create_db;
• can_scale;
• can_delete.

Even if can_scale exists as a permission, manual database lifecycle is still disabled in the current public user scenario: the database starts automatically on connection and stops after inactivity.

Tenant

A tenant is the main user isolation level. A tenant has:

• a name;
• an internal identifier;
• pg_user;
• pg_password;
• dsn_template;
• a set of databases inside the tenant.

The easiest way to think about a tenant is as a separate workspace for a project, environment, or customer.

Database

A database is a specific PostgreSQL database inside a tenant.

A database usually has:

• a name;
• a size label size;
• a state (state);
• a timeline for the storage layer;
• an internal db_id;
• runtime fields such as active_connections, worker_id, backend_addr.

For the user, the important point is that a database can be created, automatically started on first connection, then stopped after inactivity, and deleted asynchronously.

Worker and lease

These are mostly internal entities, but they are still useful to understand.

• Worker — the actual compute instance currently serving the database.
• Lease — a short-lived reservation of the backend route for Gateway, so the platform does not stop the database while it is being actively used.

This leads to two important practical consequences:

• active connections are protected from a premature stop;
• the platform can safely free compute when the database is idle.

Access model and security

All public user routes in Control Plane API v2 usually require this header:

Authorization: Bearer <API_KEY>

What is important to remember:

• the same Control Plane API is used by Console and external integrations;
• the token scope determines which objects you can see at all;
• permissions determine which actions you may perform;
• a tenant-scoped key cannot administer other tenants;
• an account-scoped key cannot work with another account.

For Console, there is one additional important nuance: login is done with the pair email + token, and the token is validated through the account profile. That is why, after the initial token issue, it makes sense to save the contact email into the account profile right away.