> ## Documentation Index
> Fetch the complete documentation index at: https://docs.auto.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Connections and Identities

> Connections grant the platform permission to act in your GitHub, Slack, Linear, and Telegram accounts; identities decide who each agent appears as and how activity is attributed.

Two separate questions decide how a factory touches the outside world. **Connections** answer "what is the platform allowed to act as?" — an installed GitHub App, an authorized Slack workspace, a Linear workspace, a Telegram bot. **Identities** answer "who does this agent appear as?" — the display name, username, and avatar an agent carries, and the attribution machinery that ties every comment, commit, and message back to the agent and session that produced it.

## Connections

A connection is an organization-level credential grant to a provider. You create one interactively from the Connections page in the web app — never in YAML: credentials are not configuration. Agent YAML then *references* connections by name, in triggers (`connection: github-acme`) and in tools; git mounts resolve the project's GitHub connection implicitly from the repository they name.

Each connection records how the platform authenticates, its **credential kind**:

| Credential kind           | Providers                                    | What it is                                             |
| ------------------------- | -------------------------------------------- | ------------------------------------------------------ |
| `github_app_installation` | GitHub                                       | The auto GitHub App installed on a user or org account |
| `oauth`                   | Slack, Linear, Discord, hosted MCP providers | An OAuth authorization of the auto app                 |
| `api_token`               | Telegram, model providers                    | A token you paste (bot token, API key)                 |

### GitHub: App installations

Connecting GitHub installs the auto GitHub App on an account. The resulting connection carries the installation id, the account (`User` or `Organization`), and a **repository selection** — either all repositories or an explicit list. Repository selection is the primary scoping lever: agents can only mount, read events from, and write to repositories the installation covers, and you can narrow the list per project.

A GitHub connection also declares which webhook **event families** it subscribes to (`pull_request`, `issues`, `issue_comment`, `check_run`, `workflow_run`, `push`, and so on). An event family the connection does not subscribe to is dropped at ingress — if a trigger on `github.workflow_run.completed` never fires, check the connection's event subscriptions first.

### Slack, Discord, Linear: workspace OAuth

Connecting Slack (or Discord, Linear) runs an OAuth flow that authorizes auto in the workspace. The grant records the provider scopes it was given; when a later platform version requests scopes the grant does not have, the connection reports the missing scopes, and reconnecting the provider re-consents to pick them up.

### Telegram: manager bot token

Telegram has no OAuth. You create a manager bot through BotFather with Bot Management Mode enabled and paste its token when connecting Telegram. The platform validates the token live and can then create per-agent persona bots through the manager (see [identities](#agent-identities) below).

### Model providers and hosted MCP providers

Two more connection families exist beyond chat and code hosts. **Model provider connections** hold API tokens for `anthropic`, `openai`, or `openrouter`, letting sessions bill model usage to your own keys. **Hosted MCP provider connections** are OAuth grants to built-in remote MCP servers — Notion, Sentry, Stripe, Vercel, Datadog, Supabase, and more — that agents consume as [tools](/reference/tools).

### Grants and project scoping

Connections live at the organization, but agents live in projects — so there is an explicit allowance step between them. A project can use a connection only after it has been allowed to that project — granted from the Connections page at connect time or later. The project-level access can further narrow the grant's resource selection, so one GitHub installation can expose different repository subsets to different projects.

At apply time, every trigger, tool, and mount that names a connection resolves it against the grants allowed to the project. A missing connection fails the apply with a diagnostic — unless the trigger is marked `optional: true`, in which case it is skipped silently and picks up automatically on the next apply after the connection appears. This is what keeps a shared `.auto/` directory or [managed template](/reference/managed-templates) portable across projects with different provider setups.

Connection changes are themselves events: when a project's usable connection set changes, the platform emits `auto.connection.established` / `auto.connection.removed`, which agents can trigger on — the standard way to run one-time setup work the moment a workspace comes online. See [lifecycle events](/reference/events/lifecycle).

## Agent identities

An identity is the face an agent presents: display name, username, avatar, and a short description. You declare it inline on the agent, and it compiles into its own identity resource named after the agent:

```yaml .auto/agents/assistant.yaml theme={null}
name: assistant
identity:
  displayName: Assistant
  username: assistant
  avatar:
    asset: .auto/assets/chatterbox.png
  description:
    The team's conversational assistant — tag @assistant on Slack or Telegram
    for quick answers, summaries, and drafts.
```

Avatar images live under `.auto/assets/` and must be square PNG or JPEG, 512–2000 px, at most 2 MiB. The description is capped at 140 characters as Slack counts them, because it becomes the bot description on chat surfaces. Field-by-field constraints are in the [identity reference](/reference/identity).

### Provider presence: dedicated bots

By default, agents speak through the workspace's shared auto app. Optionally, an agent's identity can be *realized* as a dedicated, individually-\@mentionable bot per provider — its own Slack app, its own Telegram persona bot — through an explicit per-workspace connect step for the agent's presence.

For Slack this creates and installs a real Slack app from the identity (name, avatar, description) via a browser authorization. For Telegram it is push-based: the platform mints a creation deep link, you confirm in Telegram, and the manager bot provisions the persona bot's profile and webhook. Presence is always an explicit user action — applying YAML never creates provider-side apps on its own.

### Attribution: tying activity back to sessions

Identity is also how the platform keeps events and artifacts attributable when agents and humans share the same surfaces:

* **GitHub.** All agent writes go through the shared GitHub App identity, so every agent-authored body is stamped with a visible header — avatar, bold display name, and a link back to the authoring session — bracketed by hidden, machine-readable markers. Webhook ingress parses the marker back into `github.auto.attribution { sessionId, agentName }`, so [trigger filters and routing](/concepts/triggers-and-events#attribution-knowing-who-authored-what) can distinguish agent activity from human activity and route follow-ups to the right session. Repeated edits converge on exactly one header; it is an attribution convenience, not a security boundary.
* **Chat.** Messages an agent posts carry `auto.authored: true` plus the originating session, and the platform tracks which sessions are attributed to each thread. This powers `routeBy: attributedSessions` delivery and the loopback guard that stops an agent from reacting to its own messages.

### User identity linking

Humans have identities too. In account settings (Linked identities), a user can **self-link** their GitHub or Linear account through a short OAuth flow that verifies they control it. Each mapping carries a verification level — `verified` (OAuth-proven), `confirmed`, or `asserted` (claimed by an agent, never trusted for anything sensitive).

The flagship consumer is **git attribution**: when a session was explicitly requested by a user with a verified, git-trusted GitHub identity, the sandbox authors that user's commits under their GitHub identity; otherwise it falls back to a non-linking `Requested-by:` commit trailer. An `asserted` mapping can never flip commit authorship onto a real person. Users can turn git attribution off entirely with a per-account preference.

## How the pieces fit

```mermaid theme={null}
flowchart TD
    subgraph org["Organization"]
        C1["Connection: GitHub App install"]
        C2["Connection: Slack workspace"]
    end
    subgraph project["Project"]
        A["Agent YAML<br/>connection: github-acme"]
        I["Identity: displayName,<br/>username, avatar"]
    end
    C1 -- "allowed to project,<br/>repo selection" --> A
    C2 -- "allowed to project" --> A
    I -- "realized presence" --> B["Dedicated Slack app /<br/>Telegram persona bot"]
    A -- "writes stamped with<br/>session attribution" --> C1
```

<CardGroup cols={2}>
  <Card title="Identity reference" href="/reference/identity">
    Every identity field, avatar constraints, and the generated-resource rules.
  </Card>

  <Card title="Tools reference" href="/reference/tools">
    Connection-backed tools, hosted MCP providers, and OAuth tool auth.
  </Card>

  <Card title="Mounts reference" href="/reference/mounts">
    GitHub App mount auth and the per-capability permission matrix.
  </Card>

  <Card title="Lifecycle events" href="/reference/events/lifecycle">
    Reacting to connections being established or removed.
  </Card>
</CardGroup>