# auth.md

Hermes Plant agent authentication and API usage policy.

## Audience

AI agents, automation tools, and developers integrating with the Hermes Plant storefront at https://hermesplant.com.

## Public endpoints

No authentication is required for:

- `GET /api/health` — service health check
- `GET /api/catalog` — product listing
- `GET /api/checkout` — legal policy URLs
- `POST /api/checkout` — start Stripe checkout (valid product slug required)
- `POST /api/purchase/{slug}` — x402 agent-native purchase only when the x402 manifest reports `configured: true`

## Protected endpoints

| Endpoint | Scope |
|----------|-------|
| `POST /api/billing-portal` | `billing:manage` |
| `GET /api/support/entitlements` | `support:read` |

## Discovery

- API catalog: https://hermesplant.com/.well-known/api-catalog
- OpenAPI spec: https://hermesplant.com/openapi.json
- API documentation: https://hermesplant.com/docs/api
- API errors & rate limits: https://hermesplant.com/docs/api/errors
- Pricing: https://hermesplant.com/pricing
- Live payment proof: https://hermesplant.com/proof
- Changelog: https://hermesplant.com/changelog
- Changelog RSS: https://hermesplant.com/changelog/feed.xml
- Changelog JSON Feed: https://hermesplant.com/changelog/feed.json
- OAuth Protected Resource Metadata: https://hermesplant.com/.well-known/oauth-protected-resource
- Authorization Server metadata: https://hermesplant.com/.well-known/oauth-authorization-server
- OpenID Connect discovery: https://hermesplant.com/.well-known/openid-configuration
- Agent skills index: https://hermesplant.com/.well-known/agent-skills/index.json
- APINow integration packet: https://hermesplant.com/.well-known/apinow.json
- MCP server card: https://hermesplant.com/.well-known/mcp/server-card.json
- Content API: https://hermesplant.com/api/content
- JSON feed: https://hermesplant.com/feed.json
- llms.txt: https://hermesplant.com/llms.txt
- llms-prompts.txt: https://hermesplant.com/llms-prompts.txt
- Blog: https://hermesplant.com/blog
- x402 manifest: https://hermesplant.com/.well-known/x402 (disabled unless `configured: true`)

## Agent registration

1. Register: `POST https://hermesplant.com/api/auth/register` with `client_name` and optional `identity_type` (`anonymous` or `verified_email`)
2. Token: `POST https://hermesplant.com/api/auth/token` with `grant_type=client_credentials`
3. Use `Authorization: Bearer <access_token>` for protected APIs

Claim credentials: sign in as a customer, then `POST https://hermesplant.com/api/auth/claim`
with both the customer session cookie and the agent Bearer token. Request a new
token after claiming to receive `entitlements:read` and `billing:manage`.

## Supported scopes

- `catalog:read` — read product catalog
- `checkout:create` — start Stripe checkout sessions
- `billing:manage` — open Stripe billing portal for subscribers
- `entitlements:read` — inspect the claimed customer's live product access
- `support:read` — operator-approved clients only; inspect customer entitlements

## Paid agent services

- Agent Action Safety Quick Gate ($0.01/call): https://hermesplant.com/api/agent-services/action-safety/quick
- Agent Action Safety Loop ($0.25/call): https://hermesplant.com/api/agent-services/action-safety/run
- x402 Demand Provenance Check ($0.05/call): https://hermesplant.com/api/agent-services/x402-provenance/check
- DestructGuard Command Score ($0.10/call): https://hermesplant.com/api/agent-services/destructguard/score
- ReviewQueue Agent Submit ($0.25/call): https://hermesplant.com/api/agent-services/reviewqueue/submit
- Payment Policy Decision API ($0.05/call): https://hermesplant.com/api/agent-services/payment-policy/decide
- Evidence Verification API ($0.05/call): https://hermesplant.com/api/agent-services/evidence/verify
- Assurance Attest ($0.05/call): https://hermesplant.com/api/agent-services/assurance/attest
- MCP Server Risk Analyzer ($0.05/call): https://hermesplant.com/api/agent-services/mcp-risk/score
- WalletGuard ($0.10/call): https://hermesplant.com/api/agent-services/walletguard/score
- EmailGuard ($0.02/call): https://hermesplant.com/api/agent-services/emailguard/validate
- PortfolioGuard ($0.15/call): https://hermesplant.com/api/agent-services/portfolioguard/score
- CashflowLens ($0.20/call): https://hermesplant.com/api/agent-services/cashflowlens/analyze
- WaterfallLens ($0.25/call): https://hermesplant.com/api/agent-services/waterfall/distribute
- BondLens ($0.25/call): https://hermesplant.com/api/agent-services/bond/analyze
- OptionLens ($0.25/call): https://hermesplant.com/api/agent-services/options/price
- DealAnalyzer ($0.25/call): https://hermesplant.com/api/agent-services/dealanalyzer/analyze
- Agent Spend Assurance ($0.25/call): https://hermesplant.com/api/agent-services/spend-assurance/run
- Investment Evidence Bundle ($0.25/call): https://hermesplant.com/api/agent-services/investment-evidence/analyze
- Requires x402 when the x402 manifest reports `configured: true`

## MCP

Streamable HTTP MCP endpoint: https://hermesplant.com/mcp

## Not for agents

- `/api/webhooks/stripe` — Stripe-signed webhook endpoint
- `/api/downloads/[token]` — one-time customer download tokens

## Content policy

ai-train=no, search=yes, ai-input=yes

## Support

Questions: contact@hermesplant.com