Accounts

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

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

A connected account is available for assignment; connecting it alone does not assign it to a slate. Connections and assignments explains how assignments work, and Connect an account 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:

public/slate.json

{
  "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:

.contextlayer/connections.json

{
  "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:

app/routes/home.tsx

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.

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
Create an authorization link to connect an Owner’s account
List the caller’s active accounts for a toolkit and Call a tool with the caller’s selected account, the personal-account operations that local development uses

Getting started

Core concepts

How-to

Reference

An account belongs to an Owner

Composio holds the credentials

Connect an account, then assign it

Example: a local Gmail connection

List accounts

API

​An account belongs to an Owner

​Composio holds the credentials

​Connect an account, then assign it

​Example: a local Gmail connection

​List accounts

​API

An account belongs to an Owner

Composio holds the credentials

Connect an account, then assign it

Example: a local Gmail connection

List accounts

API