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. A human creates the workspace
Every agent operates inside a topcal workspace. A human owner signs up, connects their calendar, and creates an API key in the dashboard.
Create a human account2. Issue a workspace API key
In Settings → API keys, create a key scoped for agent identity flows. Store the plaintext once — we only keep a hash.
Sign up, then open API keys3. Register + verify the human you act for
Call register_agent_identity with the prospect's email, deliver the OTP, then agent_verify_identity to receive a short-lived X-Topcal-Agent-Intent JWT with the scopes you requested.
OpenAPI: verify identity4. Provision accounts and book
With a verified intent token, call agent_signup_user to create shadow accounts, agent calendar connect to mint OAuth URLs for the human, and booking endpoints to schedule.
Full agent API referenceOAuth: two different flows
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.
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
Install the CLI, paste your API key, and probe the MCP surface:
$ npm install -g @topcal/cliexport TOPCAL_API_KEY=tofu_test_... topcal mcp probe