Teams, roles and access

Everything about who can see what. If you are working alone, you can skip this page until somebody joins.

Inviting somebody

Members → Invite. You need an email address and a role.

The invitation email carries a single-use link. Accepting it requires being signed in as that same address — a forwarded email must not let a colleague join as somebody else.

Only the hash of the invitation token is stored, so the link is shown to you exactly once, at creation. If mail is not configured on a self-hosted deployment, you get a shareable link instead of an email.

You cannot invite somebody at a role above your own.

The four roles

Ordered viewer < developer < admin < owner.

A role decides what class of action is available to you at all. It is org-wide and no grant can change it: an admin grant on one environment cannot turn a viewer into a writer, because the viewer's capability table says "cannot write" and grants do not edit that table.

Access levels

The second gate. Levels are ordered none < read < write < admin, and they apply to a specific project or environment.

Where no grant mentions a resource, the role supplies a default:

Why production is deny-by-default

A developer who needs production must be granted it explicitly, by somebody who manages members, and that grant is written to the audit log with a name attached.

The alternative — production behaving like every other environment until somebody remembers to lock it down — makes the safe state the one that requires work. Every organisation that has done it the other way has, at some point, discovered a contractor with production access nobody meant to give.

viewer gets none on production for a related reason: a viewer with read there would hold strictly more production access than a developer, which no reviewer could justify.

Grants

A grant sets a level on a whole project or on a single environment. More specific wins:

developer role                          → write on non-production, none on production
+ project grant: checkout-api = read    → read across checkout-api
+ environment grant: production = write → write on checkout-api/production

none always denies, whatever the role default would have said. That makes it the tool for carving one project out of an otherwise trusted role.

Grants are managed on each member's own page: Members → (person) → Access.

The effective-access preview

The same page shows every project and environment with the member's resolved level and the rule that produced it:

This is computed by the same function the enforcement path calls, so it cannot disagree with what actually happens. When somebody says "I can't see the staging secrets", this table is the first place to look.

Anyone can see their own row. Seeing somebody else's requires the permission to manage members.

Inviting with access already set

The invitation form lets you tick the projects and environments the person should get. When you use it, acceptance becomes deny-by-default: every project that exists at that moment gets an explicit none unless you selected it, and the ones you selected get the invited role's normal level.

A ticked production environment is the conscious act that grants production.

Projects created after they accept fall back to the role default; narrowing that is the member page's job.

Changing and removing people

"Both sides" means: to change somebody from developer to admin, you must be at least an admin yourself, to assign that role, and rank above the role they currently hold, to touch them at all. Without the second half, an admin could "demote" an owner — which is removing an owner's authority without holding it.

You cannot change or remove yourself, and an organisation can never be left without an active owner. Both are enforced inside the database transaction, not by the form.

Suspension is the right tool for "somebody is on leave" or "we are investigating". Removal is permanent, and their grants do not come back.

Custom roles

On the Enterprise plan, an organisation can define its own roles — job titles such as "Deployer" or "Contractor" — under Organisation settings → Roles, and put members on them from the member list.

• A custom role only takes away. It names a built-in role to narrow, and a member holding it keeps only the actions you tick, of those that role already has. It can never give anybody more than the role it is based on, or more than their own built-in role.
• An optional ceiling caps how far its holders reach, separately outside and inside production — "never above read in production", say. It caps explicit grants too, so a production grant written by mistake cannot get past it.
• Everybody still sees the member list. Seeing who is in the organisation is always included.
• You cannot hand out more than you hold. Defining a role needs an owner or admin who holds no custom role. Editing one, or moving somebody onto or off one, is refused if it would reach somebody beyond your authority, or switch on access grants you could not have written yourself.
• A role in use cannot be deleted. Move its members to another role, or to none, first — so nobody's access widens as a side effect of tidying up.
• Names are read, not just stored. Two roles cannot have names a colleague would read as one — "Deployer" and "deployer", or the same word in another letter width or with a lookalike letter — and no role may be named, or look like, a built-in one.
• Owners never hold a custom role; promoting somebody to owner takes theirs off.

If the organisation leaves Enterprise, existing custom roles keep applying. You can still take members off them and delete the ones nobody holds, but not define, edit or assign them.

Tokens belong to people too

A CLI token from xecret login acts as the person who created it: their role, their grants, nothing more. Revoking their membership makes every one of their devices stop working immediately.

A service token is not a person. It is pinned to one project and environment, and its actions are recorded against the token's own name — never against whoever minted it. See tokens.

Members can see and revoke their own devices under Tokens → Your devices. Admins can revoke anyone's.

A sensible starting arrangement

For a team of five to fifteen:

• Owners: two people. One is a single point of failure; five is nobody being accountable.
• Admins: whoever runs deployments.
• Developers: everybody else. They get write access to development and staging automatically, and nothing in production.
• Production: granted per person, per environment, and reviewed occasionally against the audit log.
• CI: its own service tokens, read-only, one per project and environment.

Next

• Core concepts — the hierarchy these rules apply to.
• The audit log — checking what actually happened.
• Tokens — credentials in detail.