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 who is asking: a person, or one of your backends.
The hierarchy
organization members and their roles
└── project one product
├── API keys your backends calling Gate, optionally limited to one environment
├── OAuth clients your apps signing people in
├── billing plans plans, optionally mapped to Stripe prices
└── environment development | staging | production
├── config entries versioned variables and encrypted secrets
└── Stripe connection encrypted per-environment credentialsOrganization
The top-level tenant. Each member holds a role that decides what they may change. 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.
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.
Who can do what
Gate has three kinds of access. Each answers a different question.
| Organization role | API key | OAuth client | |
|---|---|---|---|
| Who uses it | People, in the dashboard | Your backend | Your app, on behalf of a person |
| Credential | Session cookie better-auth.session_token | X-API-Key: gate_sk_… | OAuth tokens |
| Permissions come from | The member's role | The key's scopes | Your own API decides |
| Reaches | Every project in the organization | Exactly one project, optionally one environment | Your product's API, not Gate's |
Organization roles
Five fixed roles — owner, admin, developer, billing, and viewer — apply to every project
in the organization. The role matrix lists what
each may do. Dashboard access additionally needs Gate administrator access.
API key
A project's key for server-to-server calls to Gate. It has a name, a few
scopes such as config:read or usage:write,
and optionally an environment and an expiry. Every key can read its own project without a scope; it
can never change project settings, manage credentials, or reach organization routes.
OAuth client
A registered OAuth client belonging to a project. Three types, which differ in how they authenticate at the token endpoint:
| Type | API value | Token endpoint auth | Grants |
|---|---|---|---|
| Web app | web | client_secret_basic | authorization_code, plus refresh_token with offline_access |
| Native app | native | none (public client) | Same as web app |
| Machine-to-machine | service | client_secret_basic | client_credentials |
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.
What a signed-in person may do inside your product is your product's decision: read the token's
sub and apply your own rules. Gate does not store product-level roles.
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.