Concepts
This page defines the objects Bastide works with and explains how they fit together. Read it once before the other pages: the console, the API, the command line and the MCP tools all use these words in the same sense.
Overview
| Object | Belongs to | Contains or produces | Identifier |
|---|---|---|---|
| Account | a person | sessions, personal tokens, second factors | — |
| Organization | its Owners | members, projects, service accounts, a spending cap | org_… |
| Project | an organization | environments, a backend, a tier | prj_… |
| Environment | a project | variables, deployments, the release in service | env_… |
| Deployment | an environment | a build, then a release | dep_… |
| Release | a deployment | a built and signed image, promotable elsewhere | rel_… |
| Task | a project | the progress of a long-running operation | job_… |
In one sentence: an account is a member of one or more organizations; an organization owns projects; each project has its environments and its backend; a deployment builds a release and puts it into service in an environment.
Organization
The organization is a team's shared space: it owns the projects, gathers the members, and carries billing and its spending cap. It is created with the account of the person who signs up, who becomes its Owner. An account can belong to several organizations; the console asks which one to enter when you sign in. See Organizations.
Member and rank
A member is an account that holds a role in the organization, or on a single project. The hierarchical roles, from highest to lowest, are Owner (owner), Administrator (admin), Maintainer (maintainer), Developer (developer) and Reader (reader). Two cross-cutting roles come on top: Security (security) and Billing (billing).
Every operation requires a minimum rank: creating a project needs Maintainer, requesting its deletion needs Owner, reading a deployment needs Reader. Each operation's page in the MCP reference states it. A role is never granted above the rank of whoever grants it, and the organization always keeps an Owner.
Project
The project is the unit of hosting, isolation and billing: one application, its environments and its backend. It has a name (editable), a readable identifier (slug, permanent, part of its addresses), a Git repository, a production branch and a tier. See Create a project.
Environment
An environment is a deployed instance of the project, with its own variables and its own release in service. There are four kinds:
- Production (
production): created with the project, it serves your public site. The production branch deploys to it. - Staging (
staging): a copy of production to validate before promoting. - Preview (
preview): an environment attached to a branch, to review a change before merging it. - Custom (
custom): an environment you name, within the limit of your tier.
A production environment can be pinned to a release: new deployments are no longer promoted to it until the pin is lifted (environment_unpin). See Environments.
Deployment and build
A deployment is the request to put a version into an environment. It starts from a Git reference (branch, tag or commit) and goes through a build: fetching the repository, detecting the framework, installing dependencies, building and signing the image, in an isolated builder. Builds consume build minutes, counted per tier. Switching to the new version follows the health probe. See Deploy and Builds.
Release
The release is what a successful deployment built: a signed image, with its digest. It can be promoted to another environment without rebuilding (releaseId), and it is what a restore brings back: deployment_rollback puts the previous release back into service without rebuilding anything. See Restore.
Preview
Every deployment gets an immutable address, and every branch a moving address that follows its latest commit. Previews can be protected (four modes, including members-only access), and how many can run at once depends on the tier. See Previews.
Backend
The backend comes with the project: a PostgreSQL database, authentication for your application's users, object storage and realtime (enabled per project). Your application reaches it through its endpoints and a publishable key; secret keys are issued separately and shown only once. See Database, Authentication, Storage and Realtime.
Tier
The tier sets a project's resources, quotas and price. There are four: Discovery (Découverte), Standard, Pro and Sovereign (Souverain). A project starts on Discovery; the tier is changed by a person, never by an agent, because it commits spending. See Billing and Limits.
Spending cap
The spending cap limits what an organization can spend in a month. A new organization starts with a cap of €500, which the Owner then adjusts. A tier upgrade that would exceed it is refused, and raising it needs the agreement of two different people. See Billing.
Token
A token is what you present in the Authorization: Bearer … header to call the API. There are several kinds:
- the console session (
cse_…), opened with a password: eight hours at most, one hour without activity; - the personal token (
pat_…), issued by a person for a script or a workstation: it acts in their name, within the limit of their rank and of the scopes it was given; - the service account token, which acts under its own name;
- the agent token, issued to an MCP client after your consent.
Scopes (project:read, deploy:write, secrets:write…) say what a token can do, on top of its holder's rank. See Account.
Service account
A service account is a non-human identity, for continuous integration or an automated job: its tokens act under their own name, on named projects only, with named scopes and an expiry of ninety days at most. A service account reads, and only performs the writes the platform opens to it by name. See Service accounts.
MCP tool
An MCP tool is a platform operation exposed to an agent through the MCP protocol. It carries the name of its operation, with underscores in place of dots: deployment.create becomes deployment_create. Some operations are not tools, because they commit spending or a person's identity (changing tier, issuing a personal token). See MCP.
Task
A long-running operation (a deployment, a restore) returns immediately and queues a task (job_…). task_read reads its progress without keeping a connection open: read it again at a reasonable interval until it reaches a final state.
Reversible action
Every operation has a reversibility class, which decides the confirmation required:
| Class | Meaning | Example |
|---|---|---|
| N | Read only, no effect. | project_read |
| R | Reversible: runs directly, logged, can be undone. | project_create |
| E | Reversible with effort: a person approves before the call, then five minutes to undo everything in one call (action_undo). | project_settings_write, deployment_rollback |
| I | Irreversible: two-step confirmation, approval by two people, twenty-four hours of grace before the final effect. | project_delete |
See Agent safety.
Idempotency
Every write accepts an idempotency key (8 to 128 characters). Replayed with the same key, it returns the first response with no new effect: a call repeated after a network failure does not create a second project.