# auth.md — FlexExt Store AI Agent Registration & Authentication

This document provides machine-readable and human-readable instructions for autonomous AI agents, LLM assistants, and automated developer tooling to discover, register, and authenticate with FlexExt Store web services.

## 1. Discovery
Autonomous agents can discover our authorization and API boundaries at:
- **API Catalog (RFC 9727):** `https://flexext.store/.well-known/api-catalog`
- **Protected Resource Metadata (RFC 9728):** `https://flexext.store/.well-known/oauth-protected-resource`
- **OpenAPI 3.1 Specification:** `https://flexext.store/openapi.json`
- **Curated LLM Knowledge Feed:** `https://flexext.store/llms.txt`
- **Full Knowledge Base:** `https://flexext.store/llms-full.txt`

## 2. Supported Registration & Authentication Flows
FlexExt Store supports the following interaction models for artificial intelligence agents:

### A. Public Discovery & Catalog Ingestion (Zero Auth Required)
Autonomous agents (Perplexity, ChatGPT, Claude, Bing Copilot) can freely access:
- Content-negotiated storefront pages (`Accept: text/markdown` or `?format=markdown`)
- Machine-readable knowledge feeds (`/llms.txt`, `/llms-full.txt`)
- Product comparisons & pricing tiers (`/pricing.html`, `/.well-known/pricing.json`)
- Discovery metadata (`/sitemap.xml`, `/robots.txt`)

### B. User-Claimed Commercial License Verification
When an AI agent acts on behalf of a Joomla developer or merchant:
1. Agent obtains the commercial license key provided by the customer (`FLX-STORE-XXXX-XXXX-XXXX-XXXX`).
2. Agent performs an HTTP POST request to validation endpoint:
   `POST https://flexext.store/api/v1/license`
3. Request Payload:
   ```json
   {
     "license_key": "FLX-STORE-XXXX-XXXX-XXXX-XXXX",
     "domain": "customer-domain.com",
     "product": "flexext_store",
     "version": "1.17.5",
     "joomla_version": "5.2.0"
   }
   ```
4. The API cryptographically verifies the key and returns active entitlement scopes.

### C. Agent Registration & Machine Payments (WorkOS / auth.md Protocol)
For high-volume machine-to-machine integrations:
- **Registration URI:** `POST https://flexext.store/api/agent/register`
- **Token URI:** `POST https://flexext.store/api/agent/token`
- **Supported Grant Types:** `client_credentials`, `urn:ietf:params:oauth:grant-type:jwt-bearer`
- **Identity Assertions:** ID-JAG (Identity Assertion JWT) signed by recognized agent providers.
- **OAuth Discovery:** `https://flexext.store/.well-known/oauth-authorization-server`
- **Machine Payment Protocol (MPP):** `https://flexext.store/.well-known/mpp.json`
- **x402 Protocol:** `https://flexext.store/.well-known/x402.json`

## 3. Supported Scopes
| Scope | Description |
| :--- | :--- |
| `catalog:read` | Public read access to extensions catalog, documentation, and pricing. |
| `license:verify` | Real-time verification of commercial licenses and activation status. |
| `ai:ingest` | High-bandwidth ingestion of markdown documentation and AI knowledge feeds. |
| `order:manage` | Customer account order queries (requires user-scoped bearer token). |

## 4. Revocation & Token Lifespan
- Bearer tokens are short-lived (standard lifespan: 3600 seconds).
- Tokens can be revoked at any time by issuing a request to:
  `POST https://flexext.store/api/agent/revoke`
- For developer support or inquiries, contact: `support@flexext.store` or visit `https://flexext.store/contact`.