# 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