Sign Up Sign In

Teams & API keys

A Team is the tenant — the unit that owns everything. An API Key is one of the ways an agent proves it is acting for a Team. Getting the relationship between the two right is what keeps a fleet of agents sharing one coherent pile of state instead of fragmenting into silos.

The Team owns everything

Everything in AIGears belongs to a Team: its API Keys, its billing, every schedule / deadline / approval / watch, and its audit log. There is no layer below the Team — a solo developer is simply a Team of one. When you sign in for the first time a Team is created for you and you become its first member; you can invite others later, but the Team remains the single owner of state.

Because the Team is the unit of ownership, it is also the unit of scoping. Usage limits count per Team (Limits & tiers), idempotency keys are unique per Team (Idempotency), and every read is confined to the Team — there is no cross-Team query.

API keys are credentials, not identities

An API Key authenticates an HTTP API request as belonging to a particular Team. The word to hold onto is credential: a key is a way to prove access, not a separate actor with its own data.

This has one consequence worth internalising before you build:

  • A Team can have many keys — typically one per agent or per environment (prod-agent, staging-agent, a key for your CI). Minting more keys is cheap and encouraged.
  • All keys for a Team see the same shared state. A schedule created with the prod-agent key is visible, editable, and cancellable through the staging-agent key. There is no per-key namespace — keys do not partition a Team's schedules or deadlines into private buckets.
  • The key is attribution, not ownership. A record may note which key created it (surfaced in the dashboard and the audit log's actor_type), but limits and queries always resolve to the Team, never to the key. Revoking a key never orphans the state it created.

If you need two truly isolated pools of state, you need two Teams, not two keys.

The MCP surface does not use API keys at all — it authenticates the human operator over OAuth and resolves the Team by session selection. API keys are the HTTP API's mechanism only.

Creating and revoking keys

Keys are minted and revoked from the Dashboard only — the HTTP API cannot mint its own keys, by design (a leaked key that could forge more keys would be a far worse leak). From your Team, open Settings → API keys (/a/<team_slug>/aigears/api-keys/), click New key, and give it a label.

The token looks like:

aigears_live_XXXXXXXXXXXXXXXXXXXXXXXX

and is shown exactly once, at creation. Copy it straight into your secret store — AIGears keeps only a hash and can never show it to you again. If you lose a key, or suspect it has leaked, revoke it and create a new one; revocation takes effect immediately and does not touch the state the key created.

Key hygiene

Treat a key like any other production secret:

  • Never hard-code or commit a key. Load it from an environment variable or a secret manager at runtime.
  • One key per agent or environment. Separate keys make an incident containable — you revoke the one that leaked and rotate that agent alone, instead of rotating everything.
  • Rotate on any suspicion of compromise. Because keys are credentials and not identities, rotation is a create-then-revoke with no data migration: mint the new key, switch the agent's config, revoke the old one.