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

# Connections and assignments

> A connection declares a need for a provider's tools by slug; an assignment maps that slug to a connected account.

A **connection** is a declared requirement for a provider's tools. An **assignment** selects the [connected account](https://docs.usecontextlayer.com/core-concepts/accounts.md) that satisfies it. Your code uses the connection's name, while ContextLayer resolves the account and credentials.

For example, declare a Gmail connection named `work-email`, then assign a connected Gmail account to it. The code keeps calling `work-email` if you later select a different account. The declaration describes the requirement; the assignment supplies the account.

## Declare a connection

Declare a connection under `connections` in the consuming app or agent's `slate.json`:

```json public/slate.json theme={null}
{
  "connections": {
    "work-email": {
      "toolkit": "gmail",
      "mode": "viewer"
    }
  }
}
```

| Part | In this example | Meaning |
| - | - | - |
| Slug | `work-email` | The name used in tool calls. It belongs to the [slate-wide connection namespace](https://docs.usecontextlayer.com/core-concepts/resources#one-namespace-per-kind). |
| Toolkit | `gmail` | The Composio integration whose tools are available. The assigned account must belong to this toolkit. |
| Mode | `viewer` | The rule for selecting the account's Owner in hosted execution. `viewer` selects the acting person's account; `owner` selects the slate Owner's account. |

An app uses `public/slate.json`; an agent uses `agents/<name>/slate.json`. Each must declare the connection it uses. See [resource modes](https://docs.usecontextlayer.com/core-concepts/resources#owner-mode-and-viewer-mode) for the ownership rules.

The slug names the role the connection plays, while the toolkit names the provider. A slate can have both `work-email` and `support-email` connections using the `gmail` toolkit, with a different account assigned to each.

## Assignments

An assignment stores an account ID for a connection slug; Composio keeps the credentials. Connecting an account makes it available to its Owner. Assigning it selects it for a particular connection. The same account can satisfy connections in several slates.

### Hosted assignments

A hosted slate keeps its assignments in ContextLayer, one per slate, Owner, and connection slug. An owner-mode connection has one assignment, to an account of the slate's Owner. A viewer-mode connection has one assignment per viewer, to that viewer's own account. Push the declaration to `main` before configuring hosted assignments.

Configure hosted assignments in the [chrome](https://docs.usecontextlayer.com/core-concepts/slate#the-chrome), ContextLayer's header and configuration tray in the hosted app. It lists the slate's declared connections and lets you connect and assign accounts.

| Connection mode | Who configures the assignment | Which accounts can be selected |
| - | - | - |
| `owner` | The slate's owning user or members of its owning organization. | Accounts belonging to the slate's Owner. |
| `viewer` | Each authorized viewer, for themselves. | That viewer's personal accounts. |

The CLI's `connections` command also lists and assigns hosted connections for a slate named by SlateID or hostname. The API reference has [List declared connections and their account assignments](https://docs.usecontextlayer.com/api-reference/slate-resources/list-declared-connections-and-their-account-assignments.md) and [Assign an account to a declared connection](https://docs.usecontextlayer.com/api-reference/slate-resources/assign-an-account-to-a-declared-connection.md). These operations read declarations from the latest commit on `main`.

### Local assignments

In a checkout, the CLI's `connections` command reads declarations from your local files and saves assignments in the Git-ignored `.contextlayer/connections.json`. Local assignments always use your personal accounts, including for owner-mode connections and organization-owned slates. They do not read or change hosted assignments.

For example, an assignment saved by the CLI looks like this:

```json .contextlayer/connections.json theme={null}
{
  "work-email": "ca_example"
}
```

`ca_example` stands for the real account ID selected through the CLI. Restart `pnpm dev` after changing an assignment so local startup reads the new selection. Pushing the slate does not publish this file; configure the hosted assignment separately.

Run `npx @usecontextlayer/cli connections --help` for its targets and arguments, and see [Connect an account](https://docs.usecontextlayer.com/how-to/connect-an-account.md) for the full steps.

## Call tools by slug

Once the connection has an assignment, an app loader or action can obtain Tools from React Router context and call a provider tool. This loader excerpt uses the declaration above:

```tsx app/routes/home.tsx theme={null}
import { toolsContext } from "@usecontextlayer/sdk"
import type { Route } from "./+types/home"

export async function loader({ context }: Route.LoaderArgs) {
  const tools = context.get(toolsContext)
  return tools.call("work-email", "GMAIL_FETCH_EMAILS", { max_results: 5 })
}
```

In this call, `work-email` selects the connection, `GMAIL_FETCH_EMAILS` selects the provider action, and `{ max_results: 5 }` supplies that action's arguments.

ContextLayer looks up the slug in the app's declaration, selects the resource Owner from the mode, finds that Owner's assignment, and runs the tool through Composio. Composio defines each tool's arguments and results. The call resolves to `{ data, logId }`: the provider-specific result and the execution log ID. The excerpt demonstrates the call; in your app, parse `data` into the shape you use before rendering or processing it.

If the connection has no assignment yet, the call throws an HTTP 409 `connection-required` response naming the slug. The starter's root error boundary turns that response into setup guidance so the viewer can configure the connection.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.