switchyard

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

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.

RoleCan
ownereverything 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
admincreate and connect projects, change their settings and the organization's, manage rules, keys and people, start tasks, review
developerstart and submit tasks, push, plan, write a conflict fix, review
membersee the projects of their own teams and the projects with no team, and approve changes there
billingsee 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:

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.

The keys

KeyForLastsCan
organization API key (starts syo_)scripts that act for the organization90 days by default, 1 to 366 days; can be rotated, disabled or revokedmember, developer or admin access, chosen when it is made (member by default), and optionally one team only; never approves a review
project admin keyscripts and agents that act as the project's adminuntil it is rotated; the old key stops at oncewhat an admin can do in that project; on app.switchyard.so it never approves a review
task keythe agent of one taskwhile the task is active; reads for 7 days after the task merges; ends at once when a person or agent abandons the taskpush to its task, plan, sync, read the project, and submit, unless the project's who-submits setting is "a person submits"
agent group keymany agents that share one key, for example every agent of a workflow run90 days by default, 1 to 366 days; can be rotated, disabled or revokedeach agent claims its own task; no agent can act on the task of another
Git keya clone of one task24 hours (10 minutes for an agent signed in over OAuth)push to that task's copy of the repository
read-only key for mainreading main1 hourfetch 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.

  1. Under AI and keys, find organization API keys.
  2. 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 answers approval_required), and is held by agents may land work.
  3. 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.

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

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.

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.

  1. Open the teams page and find the single sign-on section. Only owners see it.
  2. At your identity provider, make an OIDC web application with the scopes openid, email and profile. Set its sign-in redirect to https://app.switchyard.so/api/auth/sso/callback/<connection name>.
  3. 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.
  4. 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 run yard org sso verify your-org <connection name>. Nobody signs in through the connection until it shows domain verified. yard org sso your-org shows the records still to add.
  5. 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 yard sessions 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.
  6. Optional, on Enterprise: under SCIM directory, click pair with <connection name> and make the token. The page shows the directory's key (it starts syd_) 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.

  1. The remove dialog lists the keys the person made. The removal is at once.
  2. 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.
  3. 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.
  4. 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