# Auth.md

BuyingMesh Agent Authentication

BuyingMesh exposes public sandbox catalog discovery without an API key. Agents may begin with `GET /agent.json`, `GET /.well-known/api-catalog`, `GET /openapi.yaml`, `GET /v1/products?environment=sandbox`, or the MCP endpoint at `POST /mcp`.

## Public discovery

- Sandbox product and supplier reads are available anonymously.
- Every public REST response uses the JSON envelope `{ "status", "data", "error" }`.
- Sandbox records are test fixtures and must not be represented as live offers.

## Production access

Production catalog access and paid query features are enabled progressively for approved buying agents. Start at `/developer-quickstart.md` and contact `ops@buyingmesh.com` to request credentials or production access. Never put credentials in a URL or expose them in a browser page.

## Agent Registration

Agent registration is required only for production access. To register an agent, send the details below to BuyingMesh and wait for an issued credential.

### Register an agent

- Registration URL: `mailto:ops@buyingmesh.com?subject=BuyingMesh%20agent%20registration`
- Agent registration endpoint: `mailto:ops@buyingmesh.com?subject=BuyingMesh%20agent%20registration`
- Agent login endpoint: not required for anonymous sandbox; production credentials are issued by email after registration review
- Authentication method: `Authorization: Bearer <issued-credential>` for production API requests
- Sign up method: email request and manual review
- Required fields: agent name, operator, intended use, callback URL, and requested catalog environment
- Account issuance: BuyingMesh replies with an API credential and scope after approval

An agent registers for production access by sending its name, operator, intended use, callback URL (if webhooks are needed), and requested catalog environment to `ops@buyingmesh.com`. BuyingMesh reviews the request and returns the appropriate API credential and scope. No registration is needed for anonymous sandbox discovery.

## MCP

Use the streamable HTTP endpoint `POST /mcp` with JSON-RPC. Discover the server through `/server.json` and `/.well-known/agent.json`. The server currently supports anonymous sandbox discovery; payment or credentials are required only when the response advertises them.

## Protected paths

`/ops/`, `/dashboard/`, and `/v1/admin/` are operator-only paths. Agents must not attempt to access them. Admin requests require the configured `Authorization: Bearer ...` or `X-Admin-Key` credential.