Аккаунты, токены и scopes

В пользовательской модели SPG99 есть несколько базовых сущностей, и почти все они управляются через Control Plane.

Account

Account — это верхний уровень клиента. К аккаунту привязаны:

• контактные данные;
• API‑ключи;
• tenants;
• usage для части биллинга.

Через account удобно разделять команды, проекты или клиентов внутри одной платформы.

API key

API key — это Bearer‑токен для обращения к Control Plane API. Он нужен для Console, автоматизации, CLI и REST‑запросов, но не используется как пароль от PostgreSQL.

У токена есть:

• scope;
• permissions;
• опциональный срок жизни.

Поддерживаются три основных scope:

• global — самый широкий административный доступ;
• account — доступ к одному аккаунту и его ресурсам;
• tenant — доступ только к одному tenant.

Права задаются отдельно. Чаще всего пользователь видит такие флаги:

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

Даже если флаг can_scale существует как permission, в текущем публичном пользовательском сценарии ручной lifecycle базы всё равно отключён: база запускается автоматически при подключении, а останавливается после простоя.

Tenant

Tenant — это основной пользовательский уровень изоляции. У tenant есть:

• имя;
• внутренний идентификатор;
• pg_user;
• pg_password;
• dsn_template;
• набор баз внутри tenant.

Tenant удобно воспринимать как отдельную рабочую зону под проект, окружение или клиента.

Database

Database — это конкретная PostgreSQL‑база внутри tenant.

У базы обычно есть:

• имя;
• размерный label size;
• состояние (state);
• timeline для storage‑слоя;
• внутренний db_id;
• runtime‑поля вроде active_connections, worker_id, backend_addr.

Для пользователя главное то, что база может быть создана, автоматически запущена при первом подключении, затем остановлена после простоя и удалена асинхронно.

Worker и lease

Это в основном внутренние сущности, но понимать их полезно.

• Worker — фактический compute‑инстанс, который сейчас обслуживает базу.
• Lease — короткоживущая «бронь» backend‑маршрута для Gateway, чтобы платформа не остановила базу во время активной работы.

Из этого следуют две важные практические вещи:

• активные подключения защищены от преждевременного stop;
• платформа умеет безопасно освобождать compute, когда база простаивает.

Модель доступа и безопасность

Все публичные пользовательские маршруты Control Plane в API v2 обычно требуют заголовок:

Authorization: Bearer <API_KEY>

Что важно помнить:

• один и тот же Control Plane API используется и Console, и внешними интеграциями;
• scope токена определяет, какие объекты вы вообще видите;
• permissions определяют, какие действия вам разрешены;
• tenant‑scoped ключ не может администрировать чужие tenants;
• account‑scoped ключ не может работать с чужим аккаунтом.

Для Console есть дополнительный важный нюанс: вход выполняется по паре email + token, а токен валидируется через профиль аккаунта. Поэтому после первичной выдачи токена имеет смысл сразу сохранить контактный email в профиле аккаунта.