Create your first shared troop

By the end of this tutorial you will have created a shared troop and invited three people into it, each with a deliberately different set of permissions: an operations lead who runs the team, a developer who configures one product, and a manager who only reads the numbers. We follow BananaSeed, a company whose founder is bringing on a team.

You need a paid plan that includes shared troops (Troop or Apex). On Solo or Alpha you have only your Personal troop, which is yours alone. See billing for plans, what a troop is for the concept, and permissions and scope for the model the roles below draw on.

The setup

BananaSeed's founder, Ana, has outgrown her Personal troop. She has two products, each with its own site key, and three people to bring in:

Each maps to one of the four permissions: Dana needs manage, Raj needs edit on one key, Mia needs read.

1. Create the troop and its keys

From the dashboard's troops list, create a troop named BananaSeed. It starts with just you, the owner, holding every permission. Create the two site keys in it, shop.bananaseed.com and blog.bananaseed.com, so there is something to scope people to. (See site keys.)

2. Invite Dana, the DevOps lead (manage)

On the troop's Members page, invite Dana by email. The invite is the email address itself; when Dana signs in with that address, her membership is live.

Grant her manage only. That single permission is troop administration: she can add, remove, and change members and access tokens, and rename or delete the troop. Because manage is troop-wide, her scope does not matter, so leave it on all site keys. She does not need read, create, or edit to do her job; manage is the team-running permission.

Now Dana can take the rest of the onboarding off Ana's hands: she can issue a CI token, add the next hire, and adjust permissions, all without being able to be locked out by scope.

3. Invite Raj, the developer on one product (edit, scoped)

Invite Raj the same way. He owns the shop, not the blog, so:

• Grant edit (and read so he can see what he is editing). Edit lets him configure the key: its settings, secret rotation, hosted verification, and the key's game and white-label customization.
• Set his scope to specific site keys and choose only shop.bananaseed.com.

Leave manage off. Raj should configure his product, not run the team. With edit scoped to one key, that is exactly what he gets: he can tune the shop's challenge and skin, and he cannot touch the blog, the members list, or the tokens.

This is the everyday least-privilege grant: a permission (edit) bounded by a scope (one key).

4. Invite Mia, the manager who only reads (read)

Invite Mia and grant read only, on all site keys. Read lets her open every key in the troop and look at its statistics, configuration, and audit logs, and change none of it. She gets the troop-wide picture she needs for reporting, with no ability to edit a setting or rotate a secret by accident.

5. Confirm each grant

Have each person sign in and check that the troop behaves as intended:

• Dana sees the Members and tokens controls and can change them, but editing a site key's own configuration is not her grant.
• Raj can open and configure shop.bananaseed.com, does not see blog.bananaseed.com, and has no Members controls.
• Mia can open any key and read its statistics, but every edit control is absent.

That is the whole point of the model: three people, three jobs, three different reaches, none of them holding more than they need. On Apex, everything each of them does is recorded under their own identity in the troop audit log.

Where to go next

• Add a CI or service credential instead of a person with a troop access token, which carries the same permissions and scope.
• Set overrides once on the troop so both keys inherit the brand.
• Watch usage across both products on the troop's statistics.

See also

• Permissions and scope: the four permissions in full.
• Seats: how each member and token consumes your plan's seat pool.
• What a troop is: the concept and what a troop owns.