# Scopes & Permissions — Apparel Monster

Agents and applications authenticate with Apparel Monster using OAuth 2.0. Every token carries one or more **scopes** that control which API operations are permitted.

## Scope list

| Scope | Grants access to |
|---|---|
| `read` | List and retrieve products, taxons, own cart, own orders, own account, addresses, wishlist. Read-only. |
| `write` | Everything `read` grants PLUS create/modify cart, apply coupons, checkout, modify own account/addresses, wishlist writes. |
| `admin` | Full Platform API — product/variant CRUD, stock management, order management, user management, taxes, shipping, promotions, reports. **Server-side only.** |

Scopes are additive: `read write` grants both. `admin` does NOT imply read/write on Storefront API — they're separate surfaces; request `read write admin` if you need both.

## Requesting scopes

### OAuth2 authorization_code (recommended for customer agents)

```
https://spree.apparel.monster/spree_oauth/authorize
  ?response_type=code
  &client_id=<CLIENT_ID>
  &redirect_uri=<CALLBACK>
  &scope=read+write
  &code_challenge=<PKCE_S256>
  &code_challenge_method=S256
  &state=<RANDOM>
```

### OAuth2 password grant

```bash
curl -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"}'
```

### OAuth2 client_credentials (admin)

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

## Per-operation security

Each operation in the OpenAPI spec declares its required scope. For example, in [`storefront.yaml`](/api/openapi/storefront.yaml):

```yaml
/checkout/complete:
  post:
    security:
      - oauth2: [write]
      - orderToken: []
```

The API allows EITHER an OAuth2 Bearer with `write` scope OR an anonymous `orderToken`.

## securitySchemes (OpenAPI)

```yaml
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://spree.apparel.monster/spree_oauth/authorize
          tokenUrl:          https://spree.apparel.monster/spree_oauth/token
          refreshUrl:        https://spree.apparel.monster/spree_oauth/token
          scopes:
            read:  Read catalog, own orders, and account
            write: Manage cart, checkout, and account addresses
            admin: Administrative access to the Platform API
        clientCredentials:
          tokenUrl: https://spree.apparel.monster/spree_oauth/token
          scopes:
            admin: Administrative access to the Platform API
        password:
          tokenUrl: https://spree.apparel.monster/spree_oauth/token
          scopes:
            read:  Read catalog, own orders, and account
            write: Manage cart, checkout, and account addresses
    bearerAuth:
      type: http
      scheme: bearer
    orderToken:
      type: apiKey
      in: header
      name: X-Spree-Order-Token
    apiKey:
      type: apiKey
      in: header
      name: X-Spree-Token
```

## Machine-readable scope metadata

- `GET /.well-known/oauth-authorization-server` — RFC 8414 metadata, `scopes_supported`, `grant_types_supported`, `code_challenge_methods_supported` (`plain`, `S256`).
- `GET /.well-known/oauth-protected-resource` — RFC 9728 metadata, `scopes_supported`, `authorization_servers`.
- `GET /api/openapi/storefront.yaml` — full OpenAPI with per-operation `security` requirements.
- `GET /?mode=agent` — JSON summary including `authentication.oauth2.scopes`.

## Agent-facing guidance

- **Start minimal.** Request only the scopes you need. Agents that request `admin` when they just want to read catalog will be treated with suspicion.
- **PKCE always.** Public clients (mobile apps, single-page agents) should use `code_challenge_method=S256`.
- **Short-lived tokens.** Access tokens are 7200 seconds (2 hours). Refresh with the `refresh_token` grant before expiry.
- **Honor `Retry-After`.** On 429, the response header tells you how long to back off.
- **Agent signing keys.** The UCP discovery at the agentic-commerce host (`https://dfe0ea20ac20.agentic.checkouttools.com/.well-known/ucp`) publishes pre-approved P-256 signing keys. If your agent signs UCP requests with a matching `kid`, authentication is automatic — no out-of-band approval needed.

## Contact the webmaster

To register an OAuth 2.0 client and receive client credentials for Storefront (`read`/`write`) or Platform (`admin`) scopes, or for ACP/UCP access beyond the pre-approved signing keys, contact the Apparel Monster webmaster. Include your integration name, requested scopes, and callback URLs.