for agents: this page is markdown at https://switchyard.so/docs/keys-and-teams.md; every page is listed in llms.txt.
Manage teams, roles and keys
Give each person the right role and each agent or script the smallest key that does its job, and know what ends when someone leaves.
You will have: members with the roles you chose, keys for your agents and scripts, and an audit log of every change. Works with: the board and yard for people and organization keys; the board, yard, MCP and REST for agent group keys; the board only to set up single sign-on, SCIM and the two-factor level, because they change who can sign in, and yard to read them. Takes: about 10 minutes.
Switchyard issues every key. No step in Switchyard asks you to paste a key into a chat. How keys and code are stored is on the security page.
Before you start
- You are an owner or admin of the organization. Agent group keys need an admin of the project.
- You are signed in with
yard login https://app.switchyard.so --github, or on the board.
Roles
An organization owns projects. Its people are its members, and each member has one of five roles. Teams group members, decide which projects a member sees, and can own paths in a project's rules.
| Role | Can |
|---|---|
| owner | everything an admin can, plus the owner-only acts: delete the organization, set its AI key, set up single sign-on and SCIM, set the IP allowlist, and require two factors |
| admin | create and connect projects, change their settings and the organization's, manage rules, keys and people, start tasks, review |
| developer | start and submit tasks, push, plan, write a conflict fix, review |
| member | see the projects of their own teams and the projects with no team, and approve changes there |
| billing | see and manage billing, and nothing else |
A member cannot start a task. Agents start tasks with a task key or an agent group key. On app.switchyard.so, the project's admin key has no person behind it, so it starts only tasks with no assignee.
People sign in with GitHub, with a link sent to their email, with Google where the sign-in page offers it, or with single sign-on where the organization set it up. Switchyard has no passwords.
What needs a browser click
Some acts are done only by a person in a browser signed in within the last 15 minutes: inviting someone, removing a member or changing a role, making or removing a team, adding someone to a team or taking them off, making, rotating, keeping or enabling an organization API key, making, rotating or enabling an agent group key, changing who gets the billing emails, changing what agents may do in the organization, scheduling a project's deletion, rotating a project's admin key, and leaving an organization. Making an organization, making a set-up code, adding a card and signing out everywhere take a browser where you are signed in, however long ago. Any agent on your laptop can use your yard sign-in, so from yard or an agent signed in over MCP these answer the error code approval_required with a link, and nothing is done. yard prints the link and exits 8. Open it, signed in as yourself, and do the act there. An organization API key never does them: it is refused with 401 or 403, or answered approval_required for an agent group key. A task key or an agent group key is refused with 403. One key keeps its acts on a project: the project's admin key makes, rotates and enables agent group keys; the organization's audit log names the key each time. Disabling or revoking an organization API key still works from yard, so a leaked key is stopped fast.
An approval of a change sent from yard or an agent waits for your click in the browser too. On the team page an owner or admin can turn on Agents may approve work (off by default; only in a browser signed in within 15 minutes). When it is on, an agent signed in as a person may approve another person's unprotected change, recorded as agent for that person. It never approves a change of its own person's task, of a task that one is stacked on, or a protected change. yard org agent-approvals your-org shows whether it is on.
Two more switches on the team page, both on by default, are changed by an owner or admin in a browser signed in within 15 minutes:
- yard and MCP access: off, every
yardsign-in and every agent signed in over MCP is refused with 403 on the organization and its projects, a person's ownyardtoo, and an open live feed of theirs ends at its next check. The board and organization API keys keep working. - agents may land work: off, a submit from a task key, an agent group key, an organization key made for an agent or any sign-in but the board's answers
approval_requiredwith the project's board, where a person submits it, whether it came over the API,yard, MCP or agit push -o submit(that push is kept, and not submitted). Pushes go on, and tasks already in the merge queue stay there. If the setting cannot be read, the submit is answered 503 (unavailable) with Retry-After, so the agent sends it again; nothing is submitted until it can be read.
A change to either switch reaches every project within 30 seconds.
Invite people and set roles
Invite a person with a role on the board's teams page, in a browser signed in within the last 15 minutes. Tick with billing to also let a developer or member manage billing. Switchyard emails the invitation. yard org invite your-org their-login invites nobody: it prints the link to the teams page and exits 8.
yard org invitations your-orglists the open invitations.yard org withdraw your-org <invitation>takes one back.- Change a role on the teams page: developer, member, admin, billing or owner.
yard org roleprints the link to the page and exits 8. - Add someone to a team or take them off on the teams page too.
yard org members your-orgshows each member with their role and teams.--team <slug>shows one team.- Make or remove a team on the teams page.
yard org team create,yard org team delete,yard org team addandyard org team removechange nothing: they print the link to the teams page and exit 8. yard account sessionslists where you are signed in.yard account sessions end <id>signs one out, and--allsigns out all of them.
The keys
| Key | For | Lasts | Can |
|---|---|---|---|
organization API key (starts syo_) | scripts that act for the organization | 90 days by default, 1 to 366 days; can be rotated, disabled or revoked | member, developer or admin access, chosen when it is made (member by default), and optionally one team only; never approves a review |
| project admin key | scripts and agents that act as the project's admin | until it is rotated; the old key stops at once | what an admin can do in that project; on app.switchyard.so it never approves a review |
| task key | the agent of one task | while the task is active; reads for 7 days after the task merges; ends at once when a person or agent abandons the task | push to its task, plan, sync, read the project, and submit, unless the project's who-submits setting is "a person submits" |
| agent group key | many agents that share one key, for example every agent of a workflow run | 90 days by default, 1 to 366 days; can be rotated, disabled or revoked | each agent claims its own task; no agent can act on the task of another |
| Git key | a clone of one task | 24 hours (10 minutes for an agent signed in over OAuth) | push to that task's copy of the repository |
| read-only key for main | reading main | 1 hour | fetch main |
The set-up shows the admin key one time only. yard branch new writes a task key to .git/yard.json in the task's clone, where yard and yard agent run read it. yard gets and renews Git keys. An agent that uses plain Git asks for a new Git key when a push is refused with 401 or 403, and sends it in a header, never in the remote address.
Make an organization API key
Make the key on the board's teams page, as an owner or admin, in a browser signed in within the last 15 minutes.
- Under AI and keys, find organization API keys.
- Type the key name, after what uses it, such as
ci. Choose its access: member (the default), developer or admin. Choose used by: a script (the default) or an agent. A key used by an agent is shown with an agent tag, never does an act that takes a browser (it answersapproval_required), and is held by agents may land work. - Click make the key. The page shows the key one time only. Copy it, then click I have copied it.
A key made on the board opens every project of the organization and lasts 90 days.
- The list shows each key's access, who made it, when it was made and last used, and when it ends.
- rotate, once you confirm on the page, shows a new key one time only. The old key keeps working for 60 minutes.
- keep for the team makes another person's key yours, so it keeps working when they leave.
- disable stops a key until you enable it. revoke stops it for good, once you confirm on the page.
yard org keys your-orglists the keys.yard org key disable|revoke your-org <key>stops one key at once fromyardtoo.revokeasks first at a terminal; a script adds--yes.yard org key create,rotate,keepandenableprint the link to this section and exit 8.
Make an agent group key
Make one agent group key for a workflow that starts many agents, in place of many task keys. Run the command in a clone of the project, as a project admin. yard prints the key one time only.
yard group create nightly
--permission commit|submit|mergesays what its tasks may do. The default is the project's who-submits setting: where a person submits each task, the group's tasks may only push.--max-tasks <n>is the most tasks the group creates in its life: 100 by default, at most 1,000.--rate <per-minute>is the most requests a minute its agents send together: 6,000 by default, 60 to 60,000.--expires-in-days <n>sets its life: 90 by default, 1 to 366.--tag key=valuetags every task it starts.
Give the key to the agents. Each agent connects to the project's MCP server with the key and calls yard_workspace_claim to take a task of its own.
yard group listshows each group with its active tasks and its most tasks.yard group <id> rotate|revoke|disable|enableacts on one group. Rotating keeps the old key working for--grace-minutes(60 by default, at most 10,080). Disabling stops the key and the keys of its tasks without revoking them.revoke --abandonalso abandons its active tasks.revokeasks first at a terminal; a script adds--yes.
On app.switchyard.so a person makes, rotates and enables agent group keys on the project's settings page, under agent groups and keys, in a browser signed in within the last 15 minutes. From yard, an agent signed in over MCP or an organization API key these answer approval_required with that page, and yard exits 8; the project admin key still makes them. Disabling and revoking work from yard.
MCP: yard_agent_group_create · REST: POST /v1/projects/<project>/fleets with the admin key and a body of name, permission, maxWorkspaces, expiresInDays, ratePerMinute and tags. The REST API page has the routes.
Rotate the project's admin key
Rotate the key on the project's settings page, in a browser signed in within the last 15 minutes, as a person with admin access to the project. The new key is shown one time only, and every earlier admin key stops at once. No key and no yard sign-in rotates it: yard project rotate-admin-key --confirm <project> answers approval_required with the settings page.
Set up single sign-on and SCIM
Single sign-on lets members sign in through your identity provider. SCIM adds and removes members from your directory. Single sign-on is on the Scale and Enterprise plans. SCIM is on Enterprise.
An owner does each step on the board, in a browser signed in within the last 15 minutes.
- Open the teams page and find the single sign-on section. Only owners see it.
- At your identity provider, make an OIDC web application with the scopes
openid,emailandprofile. Set its sign-in redirect tohttps://app.switchyard.so/api/auth/sso/callback/<connection name>. - Fill in add an OIDC connection: the connection name (lowercase letters, digits and dashes, such as
your-org-sso), the issuer URL, the email domain, the client ID and the client secret. Click add the connection. An organization has at most 2 connections, and a connection signs in at most 5 email domains. - Add the TXT record that the page shows at your DNS provider, one for each domain. The record's name is
_switchyard-sso-verification-<connection name>.<domain>. Click check the DNS record, or runyard org sso verify your-org <connection name>. Nobody signs in through the connection until it shows domain verified.yard org sso your-orgshows the records still to add. - Optional: tick require single sign-on for your organization's members. The box needs a verified connection that admits your own email. The page names the members who would be locked out. Members' other browser sessions end at once, and their
yardsessions stay. An owner whose identity provider does not answer can still sign in another way with their own two factors, and the audit log records it. - Optional, on Enterprise: under SCIM directory, click
pair with <connection name> and make the token. The page shows the directory's key (it startssyd_) one time only, and the base URL,https://app.switchyard.so/api/scim/v2. Give both to your identity provider.
The directory adds people at the connection's verified domains, with a role up to admin. It never adds, changes or removes an owner. When the directory turns a person off, their membership, team places and keys in the organization end at once. make a new token replaces the directory's key, and the old key stops at once. unpair the directory stops the key at once, and the people it added stay members.
The board registers OIDC connections. To use SAML, write to support@switchyard.so.
Members sign in through the connection with sign in with your organization (single sign-on) on the sign-in page. Your connection is verified, and the teams page shows domain verified. Next, you set the two-factor level.
Set the two-factor level
Each organization recommends two factors by default. A member without a second factor is asked to add one and is never refused. The teams page marks each member who has no two-factor: no authenticator app or passkey, no GitHub two-factor and no single sign-on.
An owner whose own sign-in has two factors can tick require two factors of the organization's members in the two-factor section of the teams page. A member without a second factor then still signs in, but the organization's pages refuse them until they add one.
The level is set. Members who need a second factor see the way to add one. yard org two-factor your-org reads the level and how members are covered.
When someone leaves
Remove a person on the board's teams page, in a browser signed in within the last 15 minutes. yard org remove your-org <login> removes nobody: it prints the link to the page and exits 8.
- The remove dialog lists the keys the person made. The removal is at once.
- To keep a shared key working, tick keep for the team for it in the dialog. A kept key keeps its rights and belongs to you from then on.
- Every other key they made ends: the organization API keys they made, and the agent group keys that they or those keys made, in every project of the organization. The task keys they hold end too, with those tasks' Git keys; the tasks and their work stay, and someone who carries one on gives it a new key with
yard branch key. A task made through an agent group key or an organization API key kept for the team keeps its keys. Anyone else who holds a key to an ended task keeps that key, but its Git keys end with the rest: they ask for a new Git key with their own task key. - When an owner or admin leaves, Switchyard rotates the project admin key of each project of the organization, and emails the remaining owners and admins. The email links to a project's settings page, where a person rotates the key again to get a new one. Switchyard never sends a key by email.
A person who leaves on their own, on the teams page, keeps nothing (yard org leave your-org prints the link to the page and exits 8), so ask an admin to keep a shared key first. A change of role ends the keys that the new role may not hold. When an owner or admin gets another role, Switchyard also rotates the project admin keys, as when they leave.
Read the audit log
Run yard org audit your-org (an owner or admin). The log lists who did what to keys, members and projects, and when. --what key, --who <login>, --since <date> and --refused narrow it. --csv or --jsonl exports it. Newer events also say whether an agent acted, the kind of actor (person, org-agent for an AgentID account, key or system), the session a yard or MCP sign-in acted in, a short mark of the key or session it used, never the secret, and the surface: board, yard, mcp or api. The API and the exports carry these fields.
The project's own history, yard log --ops, records every action in the project. Anyone with a key to the project can read it.
Verify
Run yard org members your-org to see each member's role, and yard org keys your-org to see the organization's keys. In a project clone, yard group list shows the agent groups.
Next
- Write rules and checks: give a team the paths it owns.
- Pay and set a spending limit: what the billing role can do.