# Authentication — Apparel Monster

Step-by-step guide for AI agents, integrators, and developers obtaining and using API tokens programmatically against the Apparel Monster Spree storefront.

## TL;DR — picking the right auth method

| Use case | Auth method | Header |
|---|---|---|
| Browse catalog, read products/taxons | **None** (public) | — |
| Create an anonymous cart, add items, checkout as guest | **Order token** (anonymous) | `X-Spree-Order-Token: <token>` |
| Authenticated customer (account, order history) | **OAuth2 Bearer** (password or authorization_code grant) | `Authorization: Bearer <access_token>` |
| Platform API (admin, inventory, users) | **OAuth2 Bearer** (client_credentials grant, admin scope) | `Authorization: Bearer <access_token>` |
| Store API v3 client-side | **Publishable API key** (per store) | `X-Spree-Token: <publishable_key>` |
| Agent Commerce (ACP / UCP / MCP) | Contact the webmaster for credentials | — |

## Method 1 — Anonymous (order_token)

No account required. Best for shopping agents completing a one-off checkout on behalf of a user.

```bash
# 1) Create a new anonymous cart
curl -s -X POST https://spree.apparel.monster/api/v2/storefront/cart \
  -H 'Content-Type: application/json' \
  | jq -r '.data.attributes.token' > token.txt

# 2) Use the token on all subsequent cart/checkout calls
curl -s -X POST https://spree.apparel.monster/api/v2/storefront/cart/add_item \
  -H "X-Spree-Order-Token: $(cat token.txt)" \
  -H 'Content-Type: application/json' \
  -d '{"variant_id": 118, "quantity": 1}'

# 3) Set email + shipping address
curl -s -X PATCH https://spree.apparel.monster/api/v2/storefront/checkout \
  -H "X-Spree-Order-Token: $(cat token.txt)" \
  -H 'Content-Type: application/json' \
  -d '{"order":{"email":"shopper@example.com","ship_address_attributes":{"firstname":"Jane","lastname":"Doe","address1":"500 7th Ave","city":"New York","zipcode":"10018","phone":"+15551234567","country_iso":"US","state_name":"New York"}}}'

# 4) Complete the order
curl -s -X POST https://spree.apparel.monster/api/v2/storefront/checkout/complete \
  -H "X-Spree-Order-Token: $(cat token.txt)"
```

**Lifetime:** the order_token stays valid until the order is completed or cancelled. Treat it like a session token — don't leak it to third parties.

**No registration required** for order_tokens. Agents can start transacting immediately.

## Method 2 — OAuth2 password grant (customer)

For customers with a registered Apparel Monster account.

```bash
curl -s -X POST https://spree.apparel.monster/spree_oauth/token \
  -H 'Content-Type: application/json' \
  -d '{"grant_type":"password","username":"user@example.com","password":"SECRET","scope":"read write"}'
# Response:
# {"access_token":"...","token_type":"Bearer","expires_in":7200,"refresh_token":"...","scope":"read write","created_at":...}
```

Then:
```bash
curl -s https://spree.apparel.monster/api/v2/storefront/account \
  -H "Authorization: Bearer <access_token>"
```

Refresh before expiry:
```bash
curl -s -X POST https://spree.apparel.monster/spree_oauth/token \
  -H 'Content-Type: application/json' \
  -d '{"grant_type":"refresh_token","refresh_token":"<refresh_token>"}'
```

## Method 3 — OAuth2 authorization_code with PKCE (browser-based agents, mobile apps)

1. Redirect the user to:
   ```
   https://spree.apparel.monster/spree_oauth/authorize
     ?response_type=code
     &client_id=<YOUR_CLIENT_ID>
     &redirect_uri=<YOUR_CALLBACK>
     &scope=read+write
     &code_challenge=<S256_CHALLENGE>
     &code_challenge_method=S256
     &state=<RANDOM>
   ```
2. After approval, Apparel Monster redirects to `<YOUR_CALLBACK>?code=<code>&state=<RANDOM>`.
3. Exchange the code for tokens:
   ```bash
   curl -s -X POST https://spree.apparel.monster/spree_oauth/token \
     -d 'grant_type=authorization_code' \
     -d 'code=<code>' \
     -d 'redirect_uri=<YOUR_CALLBACK>' \
     -d 'client_id=<YOUR_CLIENT_ID>' \
     -d 'code_verifier=<PKCE_VERIFIER>'
   ```

Discovery metadata (issuer, endpoints, supported grants, scopes, PKCE methods):
```bash
curl -s https://spree.apparel.monster/.well-known/oauth-authorization-server | jq .
```

## Method 4 — OAuth2 client_credentials (Platform API, admin)

For server-to-server integrations that need admin access.

```bash
curl -s -X POST https://spree.apparel.monster/spree_oauth/token \
  -H 'Content-Type: application/json' \
  -d '{"grant_type":"client_credentials","client_id":"<CLIENT_ID>","client_secret":"<CLIENT_SECRET>","scope":"admin"}'
```

Use the returned bearer token on Platform API calls:
```bash
curl -s https://spree.apparel.monster/api/v2/platform/products \
  -H "Authorization: Bearer <access_token>"
```

## Sandbox and free tier

**Anonymous catalog reads are always free, unlimited, and require zero auth.** Start making `GET /api/v2/storefront/products` calls immediately — no signup, no form, no key.

**Free cart + checkout flows** use the order_token (Method 1 above) — still no account required. The order_token is issued instantly by `POST /api/v2/storefront/cart`.

**Self-serve OAuth2 registration** for customer accounts is available at `/spree_oauth/authorize` via the standard authorization_code flow.

## Pre-approved agent signing keys

Apparel Monster's agentic-commerce host at `https://dfe0ea20ac20.agentic.checkouttools.com` publishes a public UCP discovery document that includes `signing_keys` — a list of P-256 ES256 public keys pre-approved by the agentic-commerce partner for verifying agent-signed requests:

```bash
curl -s https://dfe0ea20ac20.agentic.checkouttools.com/.well-known/ucp | jq '.signing_keys'
# [{
#   "kid": "EYW-vSS9SgOjYu_toJo44rSA-5KdWuLEOygJ5Vqjh4M",
#   "kty": "EC", "crv": "P-256",
#   "x": "ji3TGlh31opjRqClivIQMaoyLIj_cI2Yn2TtyZsxVdM",
#   "y": "QU62CgAji9exwnjt7aNP-P9BFTIFzsnpleHBpyKy-Sk",
#   "alg": "ES256", "use": "sig"
# }]
```

If your agent signs UCP requests with a key whose `kid` matches one of these, authentication is automatic — no out-of-band approval needed. Agents that want their OWN keys added to the approved set can reach out to the webmaster to submit their public key for review.

## Getting credentials — contact the webmaster

**Public Storefront API reads** need no credentials. Just start calling `GET /api/v2/storefront/products`.

**OAuth2 client credentials (for Platform API)** are issued by the Apparel Monster webmaster. To request:

- **Customer support / general API inquiries:** contact via the customer portal (see `/.well-known/agent-skills/index.json` for the canonical contact flow).
- **Integration / API keys:** request a webmaster contact — include your app name, description, requested scopes, and redirect URIs.
- **ACP / UCP / MCP agentic-commerce access** (the `https://dfe0ea20ac20.agentic.checkouttools.com` host): this is operated by our agentic-commerce partner. Reach out to the Apparel Monster webmaster to be granted access — we'll route you to the right credentials for the MCP transport, UCP capability negotiation, and ACP checkout flows. These are not self-serve today; a human review is required before agent signing keys are provisioned.

## Scopes reference

| Scope | Granted access |
|---|---|
| `read`  | List and get products, taxons, reviews, own cart, own orders, own account. |
| `write` | Create/modify carts, apply coupons, checkout operations, own account updates, addresses. |
| `admin` | Full Platform API — products, variants, stock, orders, users, reports. **Admin credentials must be kept server-side.** |

## Web Bot Auth (signing outbound requests)

If your agent signs its requests per RFC 9421 (HTTP Message Signatures), verify public keys at:
```
https://spree.apparel.monster/.well-known/http-message-signatures-directory
```

Keys are Ed25519 JWKs with `kid`, `nbf`, and `exp` lifetime fields.

## Troubleshooting

| Status | Meaning | Fix |
|---|---|---|
| `400` | Missing required params | Check request body; see OpenAPI spec. |
| `401` | Missing/invalid bearer token | Refresh token, or re-acquire via OAuth flow. |
| `403` | Wrong scope | Ensure the token has the scope listed in the OpenAPI `security` requirement for that operation. |
| `422` | Validation error | Response body's `errors` object lists per-field reasons. |
| `429` | Rate limit hit | Honor `Retry-After` header; default policy is 60 req / 60 s per IP (see `X-RateLimit-*` response headers). |

## Machine-readable references

- OAuth AS metadata (RFC 8414): `/.well-known/oauth-authorization-server`
- Protected resource metadata (RFC 9728): `/.well-known/oauth-protected-resource`
- Storefront OpenAPI: `/api/openapi/storefront.yaml` (includes `oauth2` security scheme with authorizationCode, password, clientCredentials flows and read/write/admin scopes)
- OAuth OpenAPI: `/api/openapi/oauth.yml`
- A2A agent card (with AP2 merchant extension): `/.well-known/agent-card.json`