Surfaces & authentication

AIGears has three front doors — the Dashboard, the HTTP API, and MCP — and this page explains how each one authenticates and why they all operate on the same data. It also anchors a convention you'll see throughout these docs: every operation is shown on all three surfaces, in tabs.

One product, three surfaces

A Surface is a way to read or write a Team's state. There are exactly three, and they converge on one service layer over one shared pile of Team state:

• Dashboard — a logged-in human in the browser.
• HTTP API — REST, for your code and non-MCP agent frameworks.
• MCP — an MCP-capable agent, driven by an authenticated operator.

The important consequence: anything created on one surface is immediately visible on the others. An agent can register a schedule over MCP, your code can list it over the HTTP API, and you can cancel it from the Dashboard — because none of them has its own copy of the data. They are three doors into the same room.

Throughout the guides and examples, each operation is documented in a three-tab surfaces block. The tabs are sticky: pick the surface you're building on once, and it follows you from page to page.

Dashboard: you, logged in

The Dashboard authenticates you the ordinary way — a browser session from signing in. There is no token to manage. Its home is /a/<team_slug>/aigears/, and a team switcher lets you move between the Teams you belong to.

The Dashboard is the read-heavy, trust-and-inspection surface. It is where you watch what your agents did (the Activity feed / audit log), build things by hand, mint API Keys, and decide the things only a human should decide.

HTTP API: Bearer API key

The HTTP API authenticates with an API Key sent as a bearer token on every request:

Authorization: Bearer aigears_live_XXXXXXXXXXXXXXXXXXXXXXXX

The Team is derived from the key — you never pass a team id or slug to the API. Paths are versioned under /v1/, and errors come back in a consistent envelope:

{ "error": "some_error_code", "message": "Human-readable explanation." }

Because keys are credentials and not identities, several agents can share a Team's state simply by each carrying one of its keys.

MCP: OAuth operator + selected Team

MCP has no API key. The hosted MCP server authenticates the human operator over OAuth/OIDC, not the agent and not a static token. One operator may belong to several Teams, so an MCP session begins with no Team selected and must bootstrap before any product tool:

teams_list()              → the Teams you belong to
set_current_team("acme")  → the working Team for this session

Every subsequent tool call is scoped to that Team. Call a product tool before selecting one and it returns a no_team_selected error telling the agent to run teams_list then set_current_team first. (For the exact client configuration and OAuth flow, see the MCP server reference.)

How actions are attributed

Because all three surfaces write to the same state, the audit log records which surface produced each write in an actor_type field:

• user — a human in the Dashboard.
• api_key — the HTTP API.
• mcp — an agent over the MCP server.

(Two more actors appear in the log but are not surfaces: approver, the human on the far end of an approval, and system, our own workers.)

The mcp-versus-user split is the one that matters day to day: it is what lets you tell "my agent did this" from "I did this" when you review the log.