Core concepts
Gate has a small vocabulary. Almost every endpoint is addressed by an organization, a project, or an environment, and almost every authorization decision comes down to which principal is asking.
The hierarchy
organization billing and administration boundary
└── project one product, or one deployable surface of a product
└── environment development | staging | production
├── config entries versioned variables and encrypted secrets
├── service accounts machine identities, optionally pinned here
└── Stripe connection encrypted per-environment credentialsOrganization
The top-level tenant. Members hold a control-plane role that decides what they may administer.
Organizations are archived rather than deleted; DELETE sets archivedAt and clears the caller's
active organization, and POST /organizations/{id}/restore brings it back.
Project
One product inside an organization. Creating a project automatically creates its three environments
and two project roles. Projects are also archived rather than deleted, and are addressed directly by
id — /projects/{projectId} — rather than nested under the organization.
Environment
Exactly three per project: development, staging, and production. Environments are the unit of
isolation for configuration, Stripe credentials, and usage. They cannot be created or renamed.
Principals
A principal is whatever is making a request. Gate recognises two kinds, and they behave differently in ways worth internalising early.
| User | Service account | |
|---|---|---|
| Credential | Session cookie better-auth.session_token | X-API-Key: gate_sk_… |
| Permissions come from | Control-plane role on the organization | The scopes array on the API key |
| Scope | Every organization they are a member of | Exactly one project, optionally one environment |
| Can reveal secrets | With config:reveal | With config:read |
| Can manage credentials | Yes, with credential:manage | Never |
Service account and API key
A service account is a named machine identity inside one project. It may be pinned to a single
environment, in which case any request touching a different environment is refused with 403.
Its API key carries the scopes. Scopes are control-plane permission strings such as config:read or
billing:manage, and the literal * acts as a wildcard. A key may carry between 1 and 30 scopes and
may have an expiry.
OIDC client
A registered OAuth client belonging to a project. Three types, which differ in how they authenticate at the token endpoint:
| Type | Token endpoint auth | Grants | Use for |
|---|---|---|---|
web | client_secret_basic | authorization_code, plus refresh_token with offline_access | Server-rendered and single-page web apps |
native | none (public client) | Same as web | CLIs, desktop, and mobile apps |
service | client_secret_basic | client_credentials | Backend services acting as themselves |
Clients are registered through the dashboard or
POST /api/v1/projects/{projectId}/oidc-clients. Dynamic client registration is disabled, so
POST /oauth2/register will not work.
Permissions, both kinds
This is the distinction that causes the most confusion.
Control-plane permissions
Govern administration of Gate itself. A user gets them from their organization membership role; a
service account gets them from its key scopes. The statements are
organization, member, invitation, team, ac, project, config, credential, billing,
usage, and audit. The full matrix is in
Scopes and roles.
Project permissions
Govern what your product's users may do inside your product. You define the roles, you choose the
permission strings, and you bind them to whatever principal ids you use. Gate stores them and answers
yes or no via POST /api/v1/authorize. It never interprets them.
A project role's permissions must match ^(\*|[a-z][a-z0-9_-]*:[a-z][a-z0-9_-]*)$, and a role
binding may carry an expiresAt after which it stops counting.
Accounting objects
- Usage event — an idempotent counter record, unique on
(projectId, eventId). - Billing plan — a named plan in a project, optionally mapped to a Stripe price.
- Billing account — the link between one of your subjects and a Stripe customer.
- Entitlement grant — a feature granted to a subject from a source such as
apple_iap,manual,promotion, ormigration, optionally expiring. - Audit log — an append-only record of administrative actions, including every secret reveal.
A subject is your product's identifier for whoever is being billed or entitled. Gate treats it as an opaque string; it does not have to be a Gate user id.