# auth.md

> Agent authentication and registration guide for Dash Checkout services.

## Agent Auth Metadata

```yaml
agent_auth:
  skill: shopify-app-installation
  register_uri: https://apps.shopify.com/dc-preorders
  login_uri: https://www.dashcheckout.io/login
  login_uri_template: https://www.dashcheckout.io/login?shop={shop_domain}
  identity_types_supported:
    - shopify_store
  credential_types_supported:
    - oauth2_authorization_code
  oauth_metadata:
    protected_resource: /.well-known/oauth-protected-resource
    authorization_server: /.well-known/oauth-authorization-server
  methods:
    install:
      description: Install DC Order Limits via Shopify App Store
      uri: https://apps.shopify.com/dc-preorders
      type: oauth2
    login:
      description: Login for existing users with shop domain
      uri_template: https://www.dashcheckout.io/login?shop={shop_domain}
      parameters:
        shop_domain:
          type: string
          description: Shopify store domain (e.g., mystore.myshopify.com)
          required: true
```

## Overview

Dash Checkout (DC Order Limits) is a Shopify app that provides order limit functionality for merchants. This document describes how AI agents can authenticate and interact with our services.

## Agent Registration

AI agents can access Dash Checkout functionality through the Shopify app installation flow.

### Registration Endpoints

**Interactive (form-based):**
```
https://www.dashcheckout.io/login
```

**Direct (with shop parameter):**
```
https://www.dashcheckout.io/login?shop={shop_domain}
```

Example:
```
https://www.dashcheckout.io/login?shop=mystore.myshopify.com
```

### Supported Methods

| Action | URL | Description |
|--------|-----|-------------|
| **Install (New Users)** | `https://apps.shopify.com/dc-preorders` | Install via Shopify App Store |
| **Login (Existing Users)** | `/login?shop={domain}` | Direct login for merchants who already have the app |
| **Login (Interactive)** | `/login` | Form to enter store domain |

## Authentication Flow

### Installing the App (New Users)

**Recommended: Shopify App Store**
```
https://apps.shopify.com/dc-preorders
```

1. Visit the App Store listing
2. Click "Add app"
3. Select your Shopify store
4. Authorize the requested permissions
5. App is installed and accessible from Shopify Admin

### Logging In (Existing Users)

**Option 1: Direct URL (Recommended for Agents)**
```
https://www.dashcheckout.io/login?shop={shop_domain}
```

Example:
```
https://www.dashcheckout.io/login?shop=dash-checkout.myshopify.com
```

**Option 2: Interactive Form**
1. Navigate to `https://www.dashcheckout.io/login`
2. Enter your Shopify store domain
3. Click "Login" to access the app

### For AI Agents (Programmatic Access)

| Step | Action |
|------|--------|
| 1. Discovery | Read `/.well-known/oauth-protected-resource` for resource metadata |
| 2. Install | Direct user to `https://apps.shopify.com/dc-preorders` |
| 3. Login | Construct `https://www.dashcheckout.io/login?shop={shop_domain}` |
| 4. Access | Interact via Shopify Admin or Shopify Flow |

## OAuth Metadata

| Endpoint | Description |
|----------|-------------|
| `/.well-known/oauth-protected-resource` | Resource identifier and authorization servers |
| `/.well-known/oauth-authorization-server` | Shopify OAuth endpoints |

## Public Resources (No Authentication Required)

These resources are freely accessible:

| Resource | URL |
|----------|-----|
| Marketing Website | https://www.dashcheckout.io |
| Help Center | https://help.dashcheckout.io |
| API Catalog | https://www.dashcheckout.io/.well-known/api-catalog |
| Agent Skills | https://www.dashcheckout.io/.well-known/agent-skills/index.json |
| MCP Server Card | https://www.dashcheckout.io/.well-known/mcp/server-card.json |
| LLM Content | https://www.dashcheckout.io/llms.txt |

## Scopes and Permissions

When installed, DC Order Limits requests the following Shopify scopes:

| Scope | Purpose |
|-------|---------|
| `read_products` | Access product and collection data for limit rules |
| `read_orders` | Track customer purchase history |
| `read_customers` | Identify customers for purchase caps |
| `write_cart_transforms` | Apply limits in checkout |

## Credentials

After installation, merchants access the app through the Shopify Admin. No separate API keys are issued for the marketing website.

For custom integrations, contact: hello@dashcheckout.io

## Rate Limits

The marketing website has no rate limits for public resources. The Shopify app follows Shopify's API rate limits.

## Related Specifications

- [Auth.md Specification](https://workos.com/auth-md)
- [RFC 9728 - OAuth Protected Resource Metadata](https://www.rfc-editor.org/rfc/rfc9728)
- [RFC 8414 - OAuth Authorization Server Metadata](https://www.rfc-editor.org/rfc/rfc8414)

## Contact

- **Email**: hello@dashcheckout.io
- **Support**: https://help.dashcheckout.io