# Auth.md

Stock Sorted uses **API key authentication** for the MCP server and REST API.

## MCP API Authentication (for AI Agents)

The MCP endpoint at `https://stock.sorted.fast/mcp` requires a per-shop Bearer token.

### Getting your API key

Install Stock Sorted from the Shopify App Store, then navigate to **Settings → API Access** to copy or generate your MCP API key.

### Using your API key

```http
POST /mcp HTTP/1.1
Host: stock.sorted.fast
Authorization: Bearer ss_live_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 1
}
```

### Agent Registration

Self-register to receive credentials immediately:

```http
POST https://stock.sorted.fast/api/agent/identity
Content-Type: application/json

{
  "type": "service_auth",
  "api_key": "ss_live_xxxxxxxxxxxxxxxxxxxx"
}
```

Response includes identity assertion and scopes.

### Token scopes

The MCP API key grants access to your shop's inventory data only:
- `read_inventory` / `write_inventory` — pool quantities
- `read_pools` / `write_pools` — pool configuration

### Rotating your API key

From **Settings → API Access**, click **Regenerate API Key**. The old key is immediately invalidated.

---

## Shopify OAuth (for App Installation)

Stock Sorted uses Shopify's OAuth 2.0 flow for merchant authentication.

- **Authorization endpoint:** `https://stock.sorted.fast/auth?shop={shop}.myshopify.com`
- **Required scopes:** `read_products, write_inventory, read_orders, read_locations`
- **Redirect URI:** `https://stock.sorted.fast/auth/install`

Stock Sorted uses Shopify's Session Token Exchange flow for embedded app authentication.

---

## Machine-Readable Discovery

- **MCP Server Card:** `https://stock.sorted.fast/.well-known/mcp.json`
- **Agent Card:** `https://stock.sorted.fast/.well-known/agent.json`
- **OAuth Authorization Server:** `https://stock.sorted.fast/.well-known/oauth-authorization-server`
- **OAuth Protected Resource:** `https://stock.sorted.fast/.well-known/oauth-protected-resource`