Users, groups and roles

Fadebox has two kinds of role. Global roles are platform-wide and live on the user account. Project roles apply inside one project and are granted through groups.

Global roles

TeamEnterprise

Free covers five people — only active accounts count, so deactivating one frees a seat. See Licensing.

Role	What it allows
user	The baseline every account has. On its own it grants no access to any project — you see only what a project role gives you.
template_admin	Create, edit and delete templates, and start template test runs.
admin	Everything. Manages users, groups, identity providers and runtimes; creates and deletes projects; and bypasses project roles — an admin has full authority in every project.

Admins assign global roles under Users. New accounts — including those auto-provisioned by an OIDC provider — start as user.

Project roles

Inside a project the roles are hierarchical: maintainer ⊃ editor ⊃ deployer ⊃ viewer. Holding maintainer implies everything editor may do, which implies everything deployer may do, which implies everything viewer may do.

	viewer	deployer	editor	maintainer
See the project, its environments and instances	●	●	●	●
Read repositories and registry entries	●	●	●	●
Create, deploy, stop and delete instances		●	●	●
Read instance status and logs	●	●	●	●
Create, edit, clone and delete environments — services, waves, image tags, shared variables, files			●	●
Edit or delete a protected environment; protect and unprotect one				●
Manage git repositories and registry credentials				●
Manage members and API keys				●

The line the two upper rungs draw is between doing the work and holding the keys. An editor composes: services, waves, image tags, shared variables, injected files, the blueprint flag. A maintainer also administers: who is in the project, its git and registry credentials, its API keys, its audit slice. Handing someone editor is therefore not a step towards handing them the credential store.

Creating a project is a global-admin act — you cannot be a member of a project that does not exist yet. The admin who creates one is seeded into its maintainers, so they can run it afterwards without using their global role.

Who gets which role

The roles are named after what they let you do, never after a job — the same four rungs have to serve a software team, a sales engineer's demo stacks and a trainer's labs. The translation:

The person	The role, and why
Platform or DevOps engineer running the installation	Global admin, and template_admin for whoever curates the catalog. Runtimes, identity providers, users and projects are platform-wide, so they are not a project role at all.
Tech lead or engineering manager who owns the project	maintainer. They decide who is in it, which repositories and registries it uses, and which of its environments are protected.
Developer	editor. "Run my branch against the rest" is an image tag, and adding a WireMock is a service — both are composing. They never see the member list or the credential store.
QA or tester	editor. The same, plus keeping named stacks like regression and uat configured.
Release manager	editor on the projects whose staging and uat they move — or maintainer, if those environments are protected and you have decided that moving them is an administrative act.
Support engineer reproducing a customer's bug	editor. Versions live on the environment, so "the same stack on 1.3.2" means cloning it and setting the tag on the copy, which is an editor's to do.
Sales engineer, pre-sales	editor. One demo stack per prospect, with the prospect's data image and branding.
Trainer or educator	editor. A lab per attendee, cloned from a base and varied per course.
Data or ML engineer	editor. A test bed pinned to one dataset or model version — again an image tag on an environment of their own.
Product owner, designer, salesperson	deployer. They bring the demo stack up, open its URL and show it; they never change what it is.
Stakeholder, reviewer	viewer.
CI pipeline deploying a per-pull-request instance	deployer. It deploys an environment somebody else defined.
A pipeline that writes definitions — pinning a build's image tags on the environment, or syncing environment definitions from a repository	editor. Writing a definition was never a deployer right, and maintainer would hand the pipeline your credentials and the ability to mint API keys.
Contractor or partner	Whichever of the above their work is, granted through a group scoped to the one project — see groups.
Compliance or security reviewer	Reading the audit log is not a role of its own: the project's own slice is a maintainer read, and the platform-wide log an admin one.

Two of these are worth stating as rules rather than rows. A pipeline gets the role its job needs and no more — deploying and defining are different jobs, and most pipelines only deploy. Nobody needs maintainer in order to build things; if someone is asking for it so they can change a stack, editor is the answer.

Protected environments

An environment can be marked protected, which narrows composing on that one environment back to a maintainer. It is what makes editor safe to hand out widely: everyone can build their own stacks while the shared staging stays in a few hands, instead of the whole team being kept off the composer to protect one environment.

An editor's writes to a protected environment — services, waves, image tags, shared variables, injected files, and deleting it — are refused with 403 and a message naming the flag. Raising and lowering the flag is a maintainer's act, in both directions.

Two things protection deliberately leaves alone. An editor may still clone a protected environment, and the clone is not protected — copying staging and retagging the copy is the daily path, and protection guards the original without withholding what is in it. And instances are untouched: deploying, stopping, extending and deleting instances of a protected environment stay a deployer right, because protection says who may change what the environment is, not whether it may run. See protected environments for the flag itself.

Groups are how project roles are granted

A group is a set of people. What a group grants is a set of edges of the form "every member of this group holds role in project". Users are never granted a project role directly — the grant always runs through a group, which is what makes an org-wide directory usable as the source of truth.

Membership comes from one of two places:

• Manual — an admin adds the user to the group.
• A claim mapping — an OIDC sign-in whose group claim carried a value the group maps.

Two ways to work with the same machinery

From the project — Project → Settings → Members. A maintainer starts typing a name, email or group and picks from the matches, then chooses a role — no need to know a username or a group slug by heart. The search runs on the server and reaches accounts and groups that are not in the project yet, which is why it is a maintainer's to use rather than any member's. Behind the scenes the project owns a canonical group per role, and the member is added to it; you never have to think about groups to run a project. Rows that came from a shared org group or from an SSO sync appear here read-only — revoking them belongs where they were granted.

From the platform — Access → Groups, as an admin. This is where you create groups that span projects (platform-team, qa), give them roles in several projects at once, and attach claim mappings.

Passwords

A password the account holder did not choose is temporary. That covers the generated bootstrap password, an account an admin creates with a password typed into the form, and an admin resetting somebody's password. Until it is replaced, the account can reach exactly one thing — the password form — and everything else answers 403; the create-user form says as much, so an admin knows what they are handing over.

Replacing it needs the current password, and clearing the flag frees the session already open, so nobody has to sign in twice. A user who cannot produce the current password can still sign out from that screen rather than being stuck on a dead session.

Changing your own password lives at Settings → Account. It appears only for accounts that have a password here at all: a federated user's credentials belong to their identity provider, and a service account has none, so both see a sentence saying where the credential lives instead of a form that could not work.

An account locked this way also cannot authenticate with an API key, and cannot create one — which makes forcing a reset a way to contain an account without deleting it.

Mapping identity-provider groups

Enterprise

A claim mapping puts everyone whose token carries a given value into a Fadebox group. Attaching claim mappings is an Enterprise feature; everything else on this page — groups, project roles, manual membership — is available on every tier.

A mapping always names which provider asserted the value. This matters: a bare claim value would be global, so engineering emitted by a contractor's directory would land in the same group as engineering from your corporate one — and that group carries project role grants. Scoping the match to the provider the token was verified against means an outside directory administrator cannot mint membership in your groups.

A group with no claim mappings can only be filled by hand, which includes every canonical group a project's Members view creates. The invariant throughout: a claim can only place you in a group an admin defined, and only an admin decides what that group grants.

note

Group membership from a sign-in is recomputed on each request of a signed-in SSO user, so removing someone from a directory group takes effect on their next request — you do not have to wait for a session to expire.

Service accounts

TeamEnterprise

Free covers three service accounts, an allowance separate from the one for people. See Licensing.

CI pipelines authenticate as service accounts: accounts with roles and memberships like anyone else, but with no password and no interactive sign-in. They hold API keys instead.

A key is not only a service-account thing: you can issue one for your own account too, and it carries exactly your roles and projects. Only you can create or revoke it — see Your own keys.