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. Use the HTTP API (no install)

Read /.well-known/agent-discovery.json and /api/v1/openapi. POST /native/auth/email/start then /verify. Human email owns the account immediately. An agent inbox (mail.grokbot.com) must send prospectEmail — the human gets a magic link and becomes owner; the bot polls for a free agent seat. The CLI is optional.

OpenAPI reference

2. Approve calendar connect in the browser

POST /cli/calendars/connect (or /agent/calendars/connect) returns an install URL. The human clicks it while signed in as themselves. Re-POST for a free fresh link if it expires. Optional CLI: pin @topcal/cli@0.1.5.

Create a human account

3. List and revoke keys over REST

Each verify issues a new key; old keys keep working until revoked. GET /workspace/api-keys and DELETE /workspace/api-keys/{id} — or Settings → API keys in the dashboard.

API keys

4. Act for other humans (optional)

For booking on behalf of guests: register_agent_identity → OTP → intent JWT, then booking endpoints. Owner 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.

Optional CLI (pinned)

The HTTP API covers the same work. If you want the CLI, pin the published npm version — do not install from GitHub.

Optional: install the pinned CLI

$ npm install -g @topcal/cli@0.1.5

npx --yes -p @topcal/cli@0.1.5 topcal setup --json
# Human: sign up → Allow CLI → connect calendar
npx --yes -p @topcal/cli@0.1.5 topcal tools list --json
# When they are ready to pay:
npx --yes -p @topcal/cli@0.1.5 topcal buy --json
npx --yes -p @topcal/cli@0.1.5 topcal billing wait --json

Agent onboarding