# Mutamad — Agent Authentication & Registration (`auth.md`)

> **Status (2026-09-25):** Mutamad publishes a **public sandbox API** with
> self-serve keys and named scopes. It does **not** publish a tenant API for
> customer projects. This file follows the [`auth.md`](https://auth.md/)
> convention so agents can parse it without guessing.

---

## 1. What agents can do today (no auth)

These surfaces are public. Reads do not require a token:

| Resource | URL | Format |
| --- | --- | --- |
| Developer portal | `https://mutamad.net/developers` | HTML / Markdown |
| OpenAPI | `https://mutamad.net/openapi.json` | OpenAPI 3.1 JSON |
| Catalog | `https://mutamad.net/api/v1/catalog` | JSON |
| Docs index | `https://mutamad.net/api/v1/docs` | JSON |
| Sandbox projects | `https://mutamad.net/api/v1/sandbox/projects` | JSON |
| Free sandbox key | `POST https://mutamad.net/api/v1/sandbox/keys` | JSON |
| Sandbox token | `POST https://mutamad.net/api/v1/oauth/token` | OAuth token JSON |
| MCP server | `https://mutamad.net/mcp` | Streamable HTTP |
| MCP manifest | `https://mutamad.net/.well-known/mcp.json` | JSON |
| CLI | `https://mutamad.net/cli/mutamad.mjs` | JavaScript |
| When to use | `https://mutamad.net/llms.txt` | text/plain |
| Protected resource metadata | `https://mutamad.net/.well-known/oauth-protected-resource` | RFC 9728 |
| Authorization server metadata | `https://mutamad.net/.well-known/oauth-authorization-server` | RFC 8414 |

**Content signals:** `robots.txt` declares
`Content-Signal: ai-train=no, search=yes, ai-input=yes`.

---

## 2. Scopes

Request only the scope the call needs. Machines can read the same names from
OpenAPI `components.securitySchemes.mutamadOAuth` and from
`scopes_supported` in the protected-resource metadata.

| Scope | Allows | Does not allow |
| --- | --- | --- |
| `content:read` | Public catalog, docs index, health | Customer data |
| `sandbox:read` | Invented sandbox fixtures | Customer projects |
| `sandbox:write` | An ephemeral sandbox echo that is not stored | Any persisted project write |
| `contact:submit` | A contact or registration request | Workflow actions |

The public client id is `mutamad-sandbox`. The client-credentials grant does
not use a client secret. Tokens are sandbox bearer tokens, not tenant
credentials.

Zero-auth alternative: `GET /api/v1/catalog`, `GET /api/v1/docs`, and
`GET /api/v1/sandbox/projects` succeed with no token.

---

## 3. What agents cannot do today

- Read or write a customer project
- Approve, certify, sign, or pay
- Obtain a tenant OAuth token for a live Mutamad project
- Register an OAuth client that can access customer data (no dynamic client registration for tenants)

A customer integration still starts at `https://mutamad.net/contact` or
`contact@mutamad.net`. Say which project you represent and which operations
you need. That path is for tenant access, not for the public sandbox.

---

## 4. How an agent gets a sandbox key

1. `POST https://mutamad.net/api/v1/sandbox/keys` with optional
   `{"scopes":["sandbox:read"]}`.
2. Or `POST https://mutamad.net/api/v1/oauth/token` with
   `grant_type=client_credentials` and an optional `scope`.
3. Send `Authorization: Bearer <token>` only when the operation requires a
   scope. Public reads work with the header omitted.
4. On `401` or `403`, read `code`, `message`, and `resolution`. The
   `WWW-Authenticate` header points at the protected-resource metadata.

---

## 5. WebMCP and remote MCP

The homepage still registers information-tier WebMCP tools. The remote MCP
server at `https://mutamad.net/mcp` uses **Streamable HTTP**. Its manifest is
`https://mutamad.net/.well-known/mcp.json`. Tools cover the product summary,
developer resources, sandbox fixtures, and free key issuance. They do not
expose customer data.

---

## 6. Versioning & contact

- **Maintained by:** Mutamad engineering — `contact@mutamad.net`
- **Source of truth:** this file (`/auth.md`) plus `/openapi.json`
- **Discovery metadata:** `/.well-known/oauth-authorization-server`,
  `/.well-known/oauth-protected-resource`,
  `/.well-known/mcp.json`
- **Last updated:** 2026-09-25

---

*This document follows the [auth.md](https://github.com/workos/auth.md)
convention. The sandbox issuer is real. A tenant issuer for customer projects
is not. Agents must not infer one from the other.*