# 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:

```sh
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](/rules) guide for owned paths, and the [security](/security) page for how keys and code are stored.