Create a team and add members
Set up a team in your Spec0 organisation so it can own APIs, approve subscriptions, and mint service-account tokens. Adds at least one Team Admin.
Set up a team in your Spec0 organisation so it can own APIs, approve subscriptions, and mint service-account tokens. By the end you'll have one team with at least one Team Admin.
Prerequisites
- A Spec0 organisation. The first user to sign up for Spec0 becomes its Org Owner automatically — no setup needed.
- You're signed in as an Org Owner or Org Admin. Only those roles can create teams; see the access-control reference.
Steps
1. Open the Teams page
Sign in to the dashboard, then navigate to Teams in the left nav (/teams). You'll see every team in your org. New orgs have no teams yet — that's fine.
2. Create the team
Click New team. Provide:
- Name — short, distinct. Example:
payments,growth-api. Used throughout the dashboard and in CLI invocations (--team payments). - Description (optional) — a sentence about what this team owns. Helps members joining later.
Submit. The team appears in the list immediately.
3. Add the first Team Admin
Open the team you just created (/teams/[id]) and use the Members → Invite form. For each member:
- Email — the address Spec0 sends the invite to.
- Role — pick Team Admin for at least one member. Team Admins can manage team membership and mint service-account tokens (which you'll need for the SAT recipe). Team Member is read/write on APIs but cannot manage tokens or membership.
If the invitee already exists in your org, the team membership takes effect on their next page load. If they're new, they get an email with a sign-up link; the role is applied at their first sign-in.
4. (Optional) Add more members
Repeat step 3 for each additional user. Members can belong to multiple teams — assigning someone to a second team doesn't move them, it adds them.
Verify
You should see:
- The team in
/teams. - At least one row in the team's Members table, with the Team Admin badge on at least one person.
- The team available in the team picker on
/apis(used when publishing an API) and in the CLI asspec0 push --team <name>.
Common failures
| Symptom | Cause | Fix |
|---|---|---|
New team button is missing | You're an Org Member, not Org Admin / Org Owner | Ask the Org Owner to create the team, or to promote you to Org Admin. |
| Invite email doesn't arrive | Email delivery delay or spam filter | Wait 5 minutes, check spam, resend from the Members table. |
| Invited member can't see the team | They haven't signed in since the invite | Ask them to sign out and back in. The team membership refreshes on JWT refresh. |
Next
- Issue a service-account token for this team — what you need next to wire the team into CI or an agent.
- Publish an API under this team — the CLI command that uses
--team <name>. - How teams interact with access control — the reference, if a permission check is surprising you.
Recipes
Step-by-step recipes for the most common Spec0 platform tasks. Each recipe declares its prerequisites and links to the recipes you need first.
Issue a Service Account Token (SAT) for a team
Create a team-scoped, non-interactive token for use by CI pipelines, AI agents, or any caller that's not a human at a terminal. Pick scopes deliberately and copy the token once — it's only shown at creation.