# auth.md — FlexExt 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 web services.

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

## 2. Supported Registration & Authentication Flows
FlexExt 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`)
- Real-time catalog search (`GET /index.php?route=product/search&search={term}`)
- Discovery metadata (`/sitemap.xml`, `/robots.txt`)

### B. User-Claimed Commercial License Verification
When an AI agent acts on behalf of a store owner or developer to verify software licenses:
1. Agent obtains the commercial license key provided by the customer (`FLX-XXXX-XXXX-XXXX-XXXX` or `FLEX-MP-XXXXXXXX`).
2. Agent performs an HTTP POST request to our validation endpoint:
   `POST https://flexext.dev/api/telemetry.php`
3. Request Payload:
   ```json
   {
     "license_key": "FLX-XXXX-XXXX-XXXX-XXXX",
     "domain": "customer-domain.com",
     "extension_code": "flexext_seo_analytics",
     "version": "3.9.0",
     "oc_version": "4.0.2.3"
   }
   ```
4. The API cryptographically verifies the key and returns active entitlement scopes.

### C. Agent Registration (WorkOS / auth.md Protocol)
For high-volume machine-to-machine integrations:
- **Registration URI:** `POST https://flexext.dev/api/agent/register`
- **Token URI:** `POST https://flexext.dev/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.

## 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.dev/api/agent/revoke`
- For developer support or inquiries, contact: `support@flexext.dev` or visit `https://flexext.dev/information/contact`.