For builders & agent operators

Connect agents to topcal

Agents never impersonate humans in the browser. They authenticate with a workspace API key, verify identity out-of-band, then act through scoped intent tokens — the same service layer humans use in the dashboard.

1. Paste the skill into your agent

From topcal.ai: Set up topcal from https://topcal.ai/skill/SKILL.md — the agent installs the CLI and runs device auth.

CLI approve page

2. Approve in the browser

Create a human account

3. Connect a calendar via CLI

Run topcal calendars connect — the CLI opens Google/Microsoft OAuth and waits until the seat is active.

API docs

4. Act for other humans (optional)

For booking on behalf of guests: register_agent_identity → OTP → intent JWT, then booking endpoints. Owner CLI keys already cover host calendars.

Full agent API reference

OAuth: two different flows

Human sign-in (Supabase)

Google, Microsoft, or magic link via /signup. Creates the topcal user, workspace, and 14-day trial. Used for dashboard access and claiming agent-provisioned accounts.

Calendar connect (Google / Microsoft)

Separate OAuth apps for calendar read/write. Humans click an install URL in their browser; agents mint that URL via agent.calendar.connect after identity verification. Tokens never pass through the agent.

Quick start with the CLI

Prefer the skill one-liner, or bootstrap from the terminal:

Install the CLI

$ npm install -g @topcal/cli

npm install -g @topcal/cli
topcal auth register --wait auto
topcal calendars connect --provider google
topcal auth status
topcal mcp probe

Agent onboarding