# AuthLX auth.md — Agent Registration, Authentication & API Specification

Welcome AI agents, autonomous clients, and automated integrations. This document defines the standard machine-readable Auth.md specification and OAuth 2.0 discovery mechanisms for interacting with the AuthLX Security & Software Licensing Platform.

---

## 1. Discovery Metadata & Issuer Hierarchy

AuthLX publishes RFC-compliant discovery metadata across all endpoints:

- **Primary Issuer**: `https://api.authlx.com`
- **Protected Resource**: `https://authlx.com` and `https://api.authlx.com`
- **OAuth Protected Resource Metadata (PRM, RFC 9728)**: `https://authlx.com/.well-known/oauth-protected-resource`
- **OAuth Authorization Server Metadata (RFC 8414)**: `https://api.authlx.com/.well-known/oauth-authorization-server`
- **OpenID Connect Discovery 1.0**: `https://api.authlx.com/.well-known/openid-configuration`
- **Model Context Protocol (MCP 1.0)**: `https://authlx.com/.well-known/mcp/manifest.json`
- **Autonomous Agent Integration Skill**: `https://authlx.com/.well-known/agent-skills/auth/SKILL.md`
- **LLM Discovery Manifest**: `https://authlx.com/llms.txt`
- **OpenAPI 3.0.3 Specification**: `https://api.authlx.com/openapi.json`

---

## 2. Agent Registration & Provisioning Workflows

Autonomous agents can register and provision credentials using three supported methods:

### Method 1: ID-JAG Assertion Flow (`urn:ietf:params:oauth:token-type:id-jag`)
- **Identity Type**: `identity_assertion`
- **Assertion Type**: `urn:ietf:params:oauth:token-type:id-jag`
- **Credential Types**: `bearer_token`, `jwt`
- **Registration URI**: `POST https://api.authlx.com/api/v1/agent/register`
- **Revocation URI**: `POST https://api.authlx.com/api/v1/agent/revoke`
- **Events Supported**: `https://schemas.authlx.com/events/agent-revoked`
- **Claim URI**: `POST https://api.authlx.com/api/v1/agent/claim`

### Method 2: Verified Email Assertion Flow (`verified_email`)
- **Identity Type**: `identity_assertion`
- **Assertion Type**: `verified_email`
- **Credential Types**: `bearer_token`, `jwt`
- **Claim URI**: `POST https://api.authlx.com/api/v1/agent/claim`

### Method 3: Anonymous Sandbox Handshake (`anonymous`)
- **Identity Type**: `anonymous`
- **Credential Types**: `sandbox_token`, `ephemeral_key`
- **Sandbox Auth Endpoint**: `POST https://api.authlx.com/api/v1/sandbox/auth`
- **Claim URI**: `POST https://api.authlx.com/api/v1/agent/claim`
- **Request Payload**:
  ```json
  {
    "app_id": "sandbox_demo",
    "username": "agent_evaluator",
    "hwid": "HWID-SANDBOX-TEST"
  }
  ```
- **Response**:
  ```json
  {
    "status": "success",
    "sandbox": true,
    "token": "sbx_live_session_token",
    "entitlements": {
      "plan": "free_developer",
      "features": ["hwid_lock", "unlimited_logins", "instant_reseller"]
    }
  }
  ```

---

## 3. Credential Usage & Request Signing

### Bearer Token Authentication
Include the provisioned session token in the HTTP Authorization header:
```http
Authorization: Bearer <SESSION_TOKEN>
```

### Cryptographic Hardware ID (HWID) Binding
On login and session verification, pass the computed SHA-256 or bcrypt composite hardware identifier:
```json
{
  "app_id": "YOUR_APPLICATION_ID",
  "username": "demo_user",
  "password": "SecurePassword123!",
  "hwid": "COMPOSITE_HWID_HASH"
}
```

### High-Security Signed Response Protocol (v2 HMAC)
For tamper-proof responses, compute HMAC-SHA256 of the payload using your Application Secret Key and send in headers:
- `x-signature`: `<HMAC-SHA256 hex string>`
- `x-timestamp`: `<Unix epoch milliseconds>`

---

## 4. Scopes & Permissions

| Scope | Description |
|:---|:---|
| `read` | Read public plans, health metrics, and session states |
| `write` | Manage user credentials, licenses, and applications |
| `auth:client` | Perform client user authentication and HWID binding |
| `auth:dev` | Access developer dashboard and reseller management |
| `agent:register` | Register new autonomous agent instances |
| `agent:execute` | Execute authorized MCP and API tools |

---

## 5. Rate Limits & Error Model (RFC 9457)

- Rate Limit: `100 requests / 60 seconds`
- Standard Headers: `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`
- Error Responses: All errors return `application/problem+json` formatted according to RFC 9457 with actionable `hint` and `docs_url` attributes.