# auth.md

> How an AI agent registers with and authenticates to Mitosis (mitosislabs.ai).

Mitosis is the infrastructure for AI agent replication. This document tells an
agent — or the operator running one — how to obtain credentials and call the
Mitosis APIs on a user's behalf.

## Audience

`https://mitosislabs.ai` — the Mitosis dashboard and API. Protected resources live under
`https://mitosislabs.ai/api` (for example the Backups API at `https://mitosislabs.ai/api/snapshots`).

## Discovery

Start from the machine-readable metadata; everything below is derived from it:

- Authorization server: `https://mitosislabs.ai/.well-known/oauth-authorization-server`
  (RFC 8414, includes the `agent_auth` block for agent registration flows)
- Protected resource: `https://mitosislabs.ai/.well-known/oauth-protected-resource` (RFC 9728)
- OpenID configuration: `https://mitosislabs.ai/.well-known/openid-configuration`
- Agent card (A2A): `https://mitosislabs.ai/.well-known/agent-card.json`
- Agent skills index: `https://mitosislabs.ai/.well-known/agent-skills/index.json`
- Service docs for agents: `https://mitosislabs.ai/llms.txt` and `https://mitosislabs.ai/llms-full.txt`

## Identity types supported

- `service_auth` — an operator registers an account, provisions an agent, and
  receives a scoped credential (API key / JWT) used as a Bearer token.
- `anonymous` — public discovery documents and read-only agent endpoints are
  reachable with no credential.

## Zero to first call

Each step below is live and verifiable right now, with no human in the loop
until a credential is needed.

1. **Zero-auth access (works this second).** The public API needs no key:

   ```bash
   curl https://mitosislabs.ai/api/v1/pricing
   curl https://mitosislabs.ai/api/v1/status
   ```

   Both return JSON with a 200. The full anonymous surface is listed in
   `https://mitosislabs.ai/openapi.json` (every path with an empty `security` array).

2. **Sandbox (free, no billing).** `https://dev.mitosislabs.ai` mirrors every
   route with disposable data and Stripe test mode. Verify it:

   ```bash
   curl https://dev.mitosislabs.ai/api/v1   # → "environment": "sandbox"
   ```

3. **Free evaluation.** Every plan starts with a 7-day free trial and nothing is
   charged until it ends (`https://mitosislabs.ai/pricing.md`). Reading a memory over MCP or
   the API is free of per-call charges; credits meter data volume only.

4. **Self-serve credential.** No sales call and no form. The operator signs in
   with Google at `https://mitosislabs.ai/login`, then either:
   - runs `npx -y -p @mitosislabs/sdk@latest mi login` — a device-code flow
     that opens the browser once and writes an `mi_` API key to
     `~/.os1/config.json`; or
   - uses the dashboard user menu → **Copy API Key**, which calls
     `POST https://mitosislabs.ai/api/auth/sdk-key` (session-authenticated) and returns
     `{"key": "mi_…"}`.

5. **First authenticated call.** Send the key as a bearer token to the MCP
   server (`POST https://mitosislabs.ai/api/mcp`, tool `cortex_status`) or to the account
   API (`GET https://mitosislabs.ai/api/snapshots`).

## Register (service_auth)

1. An operator creates an account at `https://mitosislabs.ai/login` (the `register_uri`;
   `https://mitosislabs.ai/signup` redirects there). Sign-in is Google OAuth; there is no
   separate registration form.
2. Generate a credential self-serve: `mi login` (device-code flow) or the
   dashboard's **Copy API Key** action (`POST https://mitosislabs.ai/api/auth/sdk-key`). The
   key is an `mi_`-prefixed bearer token bound to that operator's offices.
3. Store the credential securely. It is the agent's bearer token.

Programmatic access uses the Mitosis SDK:

```bash
npm install -g @mitosislabs/sdk
```

## Use (Bearer token)

Send the credential as an HTTP `Authorization` header. `header` is the only
`bearer_methods_supported` value advertised by the protected-resource metadata:

```http
GET https://mitosislabs.ai/api/snapshots
Authorization: Bearer <token>
```

## Scopes

`backups:read`, `backups:write`, `backups:admin`, plus the OIDC scopes
`openid`, `profile`, `email`. See `scopes_supported` in the authorization
server metadata for the authoritative list.

## Revocation

Credentials are revoked from the operator's dashboard. A revoked token fails
closed: protected endpoints return `401 Unauthorized`. Re-register (provision a
new agent credential) to obtain a fresh token.

## Anonymous access

The discovery documents above and any read-only agent endpoints require no
credential. No claim ceremony is needed to read them.

## Sandbox / test environment

Every route in this document also exists on the sandbox at
`https://dev.mitosislabs.ai` — disposable data, Stripe test mode, no billing
side effects. Credentials are scoped per environment: sandbox keys do not work
in production and vice versa. Verify which environment you are on with
`GET /api/v1` (`"environment": "sandbox"` vs `"production"`). Full guide:
https://dev.mitosislabs.ai/api/v1