Connect an account

Connect a Gmail account, then assign it to a connection named work-email. This guide uses a viewer-mode connection: each person supplies their own Gmail account on the hosted slate. It shows local and hosted setup separately because they save different assignments. Before you start, sign in to the CLI as described in Installation and work from a private slate’s checkout. If your personal Owner already has a connected Gmail account, skip account authorization and go straight to assignment. Add work-email to the app’s existing connections object in public/slate.json. Keep its other declarations. For a starter app that still uses the notes database, the result is:

public/slate.json

{
  "connections": {
    "work-email": { "toolkit": "gmail", "mode": "viewer" }
  },
  "databases": {
    "notes": { "mode": "owner" }
  }
}

work-email is the connection slug the app passes to tools.call. gmail identifies the provider toolkit, and viewer selects the acting person’s account on the hosted slate. See Owner mode and viewer mode for the alternative of using one shared account.

Connect the account

The local workflow below uses an account connected for your personal Owner. If you are configuring an owner-mode connection for an organization instead, select that organization when connecting the account; see Personal and organization Owners.

Run the accounts command

Connect a Gmail account for your personal Owner:

npx @usecontextlayer/cli accounts add gmail

The command prints an authorization link and suggested assignment commands. Run npx @usecontextlayer/cli accounts --help for account listing and other options.

Authorize in the browser

Open the link, sign in to the Gmail account you want the slate to use, and approve the provider’s requested access. If a coding agent is running the CLI, it should give this link to you and wait for you to complete authorization.The external account you authorize and the ContextLayer Owner holding it are separate choices. This walkthrough connects the Gmail account for your personal Owner.

Assign it in local development

Assign the account to the connection

From the checkout root, assign a connected Gmail account to work-email:

npx @usecontextlayer/cli connections local assign work-email

Choose the Gmail account you authorized from the interactive picker. The CLI offers your personal accounts for the connection’s toolkit and saves the selected account ID in the checkout’s ignored .contextlayer/connections.json. Use npx @usecontextlayer/cli connections --help for noninteractive assignment and other targets.

Restart the development server

Restart pnpm dev. The development server reads declarations and local assignments at startup. Open the local app and run the route that calls work-email to verify it can use the account.

Local development always uses your personal accounts, even for an owner-mode connection or a slate that belongs to an organization.

Assign it on the hosted slate

Commit and push the connection declaration, then wait for the hosted app to deploy; see Deploy. Hosted assignments use pushed declarations and are saved in ContextLayer. The local assignment file is not uploaded. Use the hosted app’s chrome, the ContextLayer header and configuration tray, to select the account. You can reuse the personal account you already connected without repeating provider authorization.

Open the hosted slate

Open the slate’s hosted URL and sign in with your ContextLayer account.

Choose the account

Open the connection’s settings and select your connected Gmail account.If the account is not listed, select Connect account. The authorization opens in a new tab. When you have connected the account, refresh the slate and choose it.The chrome connects the account for the connection’s Owner: you for a viewer-mode connection, the slate’s Owner for an owner-mode connection.

Refresh the page

Refresh the slate and run the app operation that uses work-email. The hosted call now uses the account you selected in the chrome.

The platform API exposes the same operations: Create an authorization link to connect an Owner’s account and Assign an account to a declared connection.

Personal and organization Owners

An Owner is either personal (one user) or an organization. Every account belongs to one Owner, independently of any slate. Slates use an account through assignments; an assignment stores the account’s ID, never its credentials. The accounts command acts for your personal Owner by default and can act for an organization you are a member of; its --help shows how. Any member of an organization can connect and manage the organization’s accounts. An account a member connects for the organization belongs to the organization.

Owner mode and viewer mode

Each declared connection has a mode. It selects whose account the hosted slate uses.

Owner mode: the slate’s Owner’s account. Every user of the slate uses this one account. Assigning it requires managing the slate: being its owning user or a member of its owning organization.
Viewer mode: each user’s own personal account. Each viewer connects and assigns their own in the chrome; see Use a slate.

Use the connection in app code

Once the assignment is saved, the app can call Gmail through work-email. This excerpt demonstrates a loader call, not a complete route or email interface. Merge the call into your route without removing its existing data or rendered component, and validate the provider result before using it:

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)
	const { data } = await tools.call("work-email", "GMAIL_FETCH_EMAILS", { max_results: 5 })
	return { result: data }
}

Getting started

Core concepts

How-to

Reference

Connect the account

Run the accounts command

Authorize in the browser

Assign it in local development

Assign the account to the connection

Restart the development server

Assign it on the hosted slate

Open the hosted slate

Open the setup menu

Choose the account

Refresh the page

Personal and organization Owners

Owner mode and viewer mode

Use the connection in app code

​Connect the account

Run the accounts command

Authorize in the browser

​Assign it in local development

Assign the account to the connection

Restart the development server

​Assign it on the hosted slate

Open the hosted slate

Open the setup menu

Choose the account

Refresh the page

​Personal and organization Owners

​Owner mode and viewer mode

​Use the connection in app code

Connect the account

Assign it in local development

Assign it on the hosted slate

Personal and organization Owners

Owner mode and viewer mode

Use the connection in app code