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

# Accounts

> A connected account holds a provider's credentials for a personal or organization Owner, independently of any slate.

An **account** is an authorized connection to an external service, such as Gmail or Slack. Composio holds its provider credentials, and ContextLayer uses the account to call that service's tools. This connected account is separate from the ContextLayer account you use to sign in.

An account is separate from the requirement a slate declares. The slate might require Gmail through a connection named `work-email`; an assignment chooses which connected Gmail account satisfies that requirement.

## An account belongs to an Owner

Every account belongs to an [Owner](https://docs.usecontextlayer.com/core-concepts/owners-and-viewers.md): a person or organization. It belongs to that Owner independently of any slate, so several slates can use the same account without creating separate provider logins for each one.

Choose the Owner when connecting the account. A personal account belongs to you. An account connected for an organization belongs to that organization, and its members can connect and list the organization's accounts. The person completing provider authorization and the Owner holding the resulting account can therefore be different: an organization member can authorize an organization-owned account.

## Composio holds the credentials

Composio stores and refreshes the provider credentials. A ContextLayer assignment records an account ID, not an access token or password. Tool calls run in a Composio session for the Owner selected by the connection's mode, so an assignment can select only an account belonging to that Owner.

Your app or agent calls a tool through a declared connection; it does not need to load or refresh the provider credential itself.

## Connect an account, then assign it

Connecting and assigning are two separate actions:

1. **Connect the account.** Choose its Owner and toolkit—the provider integration, such as Gmail. ContextLayer creates an authorization link; complete the provider's authorization in your browser.
2. **Assign the account.** Select the connected account for a connection declared by the slate. This tells that connection which account to use.

You can start account authorization from:

* the CLI's `accounts` command, which prints the link;
* the [chrome](https://docs.usecontextlayer.com/core-concepts/slate#the-chrome), ContextLayer's header and configuration tray in a hosted slate, next to a declared connection;
* the API operation [Create an authorization link to connect an Owner's account](https://docs.usecontextlayer.com/api-reference/accounts/create-an-authorization-link-to-connect-an-owners-account.md).

A connected account is available for assignment; connecting it alone does not assign it to a slate. [Connections and assignments](https://docs.usecontextlayer.com/core-concepts/resources/connections-and-assignments.md) explains how assignments work, and [Connect an account](https://docs.usecontextlayer.com/how-to/connect-an-account.md) provides the procedure.

During local development, connections always use your personal accounts, regardless of the slate's Owner or the connection's mode. Connect the account for yourself when you want to use it locally.

## Example: a local Gmail connection

For example, an app declares a Gmail connection with the slug `work-email`:

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

Assigning one of your Gmail accounts through the CLI saves its ID under the connection slug in the checkout's ignored `.contextlayer/connections.json` file. For example:

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

`ca_example` represents the connected account's ID. The CLI writes the actual ID when you make the assignment; this file contains no Gmail credentials and stays out of Git. A hosted assignment is configured separately and is not read from this local file.

This loader excerpt calls the provider tool through `work-email`. The slug stays in code; changing the assignment changes the selected account without changing the loader:

```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 })
}
```

The call returns `{ data, logId }`: the provider's result and the execution log ID. Validate provider data before using it in your interface; see [Tools in the SDK reference](https://docs.usecontextlayer.com/reference/sdk.md#tools).

## List accounts

Use the account list to choose an active account for an assignment. The CLI's `accounts` command lists an Owner's accounts with their toolkit, identity, and status. Only active accounts are listed. Run `npx @usecontextlayer/cli accounts --help` for its operations and for choosing between your personal accounts and an organization's.

## API

The platform's account operations are in the Accounts group of the API reference:

* [List active accounts belonging to an Owner](https://docs.usecontextlayer.com/api-reference/accounts/list-active-accounts-belonging-to-an-owner.md)
* [Create an authorization link to connect an Owner's account](https://docs.usecontextlayer.com/api-reference/accounts/create-an-authorization-link-to-connect-an-owners-account.md)
* [List the caller's active accounts for a toolkit](https://docs.usecontextlayer.com/api-reference/accounts/list-the-callers-active-accounts-for-a-toolkit.md) and [Call a tool with the caller's selected account](https://docs.usecontextlayer.com/api-reference/accounts/call-a-tool-with-the-callers-selected-account.md), the personal-account operations that local development uses


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