for agents: this page is markdown at https://switch-yard.dev/docs/keys-and-teams.md; every page is listed in llms.txt.
Teams, roles and keys
In this guide you will set up who can do what: the organization and its teams, the roles people hold, and the keys agents and scripts use. One rule runs through it all: keys are issued by the product and never passed around in chat, and nothing in Switchyard will ever ask you to paste one.
Organization, teams, roles
An organization owns projects. Its people are its members, each with one of three roles; teams group members, decide which projects a member sees, and can be named in a project's rules as the owners of paths whose changes they must approve.
| Role | Can |
|---|---|
| owner | everything an admin can, plus deleting the organization and setting its Anthropic key |
| admin | create and connect projects, change their settings and the organization's, start tasks, review, pause merging, merge a hotfix |
| member | see the projects of their own teams and those with no team, review changes there |
A member cannot start a task; agents start tasks with the project's admin key, a task key or an agent group key, and admins start them signed in.
How people sign in
People sign in with GitHub, or with a link sent to their email, on the app or from the terminal with yard login https://app.switch-yard.dev --github, which prints a link and a code to approve in the browser; no password exists. The account page lists where you are signed in and signs any of them out, or all of them at once. A session signed out elsewhere stops working at once where it was signed out, and within a second everywhere else.
The keys
| Key | For | Lasts | Can |
|---|---|---|---|
organization API key (syo_) | scripts acting for the organization | 90 days by default, 1 to 366; rotated, disabled or revoked | member or admin, chosen when it is made (member by default), optionally limited to one team |
| admin key | scripts and agents that act as the project's admin | until rotated from the settings page or with POST /admin-key/rotate; the old key stops at once, with no grace period | everything an admin can in that project |
| task key | one task's agent | while the task is active; read-only once it merges; stopped with its agent group key | push to its task, plan, sync, read the project; submit, which is the default (the agent submits when the work is done), unless the project chose "a person submits" in its settings or the key was issued with commit permission |
| agent group key | many agents sharing one key, such as every agent of a workflow run | 90 days by default, 1 to 366; rotated, disabled or revoked | each agent claims its own task; no agent can act on another's |
| Git key | a clone of one task | 24 hours | push to that task's copy of the repository |
| read-only key for main | reading main | 1 hour | fetch main and a change's versions |
The admin key is shown once, when the project is set up. A task key is written to the task checkout's .git/yard.json by yard branch new, where the CLI and yard agent run read it; it is never printed. Git keys are issued on demand and renewed by the CLI; an agent using plain Git asks for a fresh one when a push is refused with 401 or 403 and sends it in a header, never in the remote address.
Agent group keys
For a workflow that starts many agents, issue one agent group key instead of many task keys. It is created, rotated, disabled and revoked through the API as the project's admin:
curl -X POST https://app.switch-yard.dev/v1/projects/<project>/fleets \
-H "Authorization: Bearer <admin key>" \
-H "content-type: application/json" \
-d '{"name": "nightly", "permission": "submit", "maxWorkspaces": 50, "expiresInDays": 30}'
The answer carries the key once. Each agent connects to the MCP server with it and calls yard_workspace_claim to take a task of its own; the key's tags, such as the run it belongs to, are on every task it creates. Rotation gives a new secret with a grace period for the old one; disabling stops the key and its tasks' keys without revoking them; revoking ends it and, if asked, abandons its active tasks. Each of these is written to the organization's audit log.
What is logged
The organization's audit log records who did what to keys, members, secrets and projects, and when: a key issued, rotated or revoked, a member's role changed, an operator moving a repository's branches back or rewinding a project's record. It is readable by the organization's owners and admins. The project's own history records every action in the project and is readable by anyone with a key to the project, task keys included.
What you have now
People with roles, agents with the smallest key that does their job, and a log of every change to either. Next: the rules and checks guide for owned paths, and the security page for how keys and code are stored.