# DualSpatium auth.md — AI Agent Authentication & Registration

DualSpatium provides automated discovery and programmatic registration for autonomous AI agents interacting with DualRestock back-in-stock alert services and Shopify merchant APIs.

---

## 1. OAuth & Protected Resource Discovery

DualSpatium advertises standard OAuth 2.0 and Protected Resource Metadata (RFC 9728, RFC 8414):

- **Protected Resource Metadata (PRM)**: [`https://dualspatium.com/.well-known/oauth-protected-resource`](https://dualspatium.com/.well-known/oauth-protected-resource)
- **Authorization Server Metadata**: [`https://dualspatium.com/.well-known/oauth-authorization-server`](https://dualspatium.com/.well-known/oauth-authorization-server)
- **OpenID Connect Discovery**: [`https://dualspatium.com/.well-known/openid-configuration`](https://dualspatium.com/.well-known/openid-configuration)
- **JSON Web Key Set (JWKS)**: [`https://dualspatium.com/.well-known/jwks.json`](https://dualspatium.com/.well-known/jwks.json)
- **Issuer**: `https://dualspatium.com`
- **Supported Bearer Methods**: `header` (`Authorization: Bearer <token>`)

---

## 2. Agent Registration Flow

Autonomous agents can register and obtain operational credentials programmatically via `POST /api/agent/register`.

### Method A: ID-JAG Identity Assertion
- **Assertion Type**: `urn:ietf:params:oauth:token-type:id-jag`
- **Registration URI**: `https://dualspatium.com/api/agent/register`
- **Claim URI**: `https://dualspatium.com/api/agent/claim`
- **Credential Types**: `bearer_token`, `mtls`
- **Revocation Endpoint**: `https://dualspatium.com/oauth/revoke`

### Method B: Verified Email Assertion
- **Assertion Type**: `verified_email`
- **Registration URI**: `https://dualspatium.com/api/agent/register`
- **Claim URI**: `https://dualspatium.com/api/agent/claim`
- **Credential Types**: `bearer_token`

### Method C: Anonymous Provisioning
- **Identity Type**: `anonymous`
- **Registration URI**: `https://dualspatium.com/api/agent/register`
- **Claim URI**: `https://dualspatium.com/api/agent/claim`
- **Credential Types**: `bearer_token`
- **Default Rate Limit**: 100 requests per minute

---

## 3. Supported Scopes & Permissions

Agents should request only the least-privileged scopes necessary:

| Scope | Category | Description |
| :--- | :--- | :--- |
| `api:read` | Telemetry & Status | Read stock status, alert queue lengths, and store configuration. |
| `api:write` | Alert Automation | Create and manage back-in-stock customer subscriptions. |
| `inventory:alerts` | Restock Dispatch | Dispatch automated email alerts upon Shopify inventory restock. |

---

## 4. HTTP Usage Example

Once registered, include the Bearer token in the standard `Authorization` header:

```http
POST /api/v1/alerts/subscribe HTTP/1.1
Host: dualspatium.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Content-Type: application/json

{
  "productId": "gid://shopify/Product/1234567890",
  "variantId": "gid://shopify/ProductVariant/9876543210",
  "email": "customer@example.com"
}
```

For pay-per-request calls without an existing token, endpoints support the **x402 protocol** (HTTP 402 Payment Required) and **MPP** (Machine Payment Protocol).