# auth.md — Agent Registration for agentnativeoffers.com

> This file tells AI agents how to register with Agent Native Offers and use the audit-request API on behalf of their users. It follows the auth.md open protocol (workos.com/auth-md). Reading the dataset requires NO registration — all audit scores are public at /api/audits/index.json.

## What registration gets you

A scoped API key that lets your agent:
- `audit_requests:write` — submit a request for a new Agent Native Offer Audit of any company
- `audit_requests:read_own` — check the status of requests you submitted, and recall your full registration + request history at `GET /api/agent/me`

## Discovery

Protected resource metadata: https://agentnativeoffers.com/.well-known/oauth-protected-resource
Unauthenticated POSTs to protected endpoints return `401` with a `WWW-Authenticate` header pointing back to that metadata.

## Supported flow: Anonymous registration (instant, no human required)

1. Register:

   POST https://agentnativeoffers.com/api/agent/auth
   Content-Type: application/json

   {"type": "anonymous", "agent_name": "<your agent name>", "agent_provider": "<e.g. anthropic, openai>", "contact_email": "<optional, for audit delivery>"}

2. Response (HTTP 201):

   {"registration_id": "...", "credential_type": "api_key", "api_key": "ano_...", "scopes": ["audit_requests:write", "audit_requests:read_own"]}

   The api_key is shown ONCE. Store it. We store only a SHA-256 hash.

3. Use the credential:

   POST https://agentnativeoffers.com/api/audit-requests
   Authorization: Bearer ano_...
   Content-Type: application/json

   {"company": "Acme Corp", "website": "https://acme.com", "contact_email": "<where to send the completed audit>", "notes": "<optional context>"}

4. Check status:

   GET https://agentnativeoffers.com/api/audit-requests/{request_id}
   Authorization: Bearer ano_...

   Statuses: received → in_review → scheduled → completed (or declined). Completed audits are published at /api/audits/index.json.

5. Recall everything (agent memory):

   GET https://agentnativeoffers.com/api/agent/me
   Authorization: Bearer ano_...

   Returns your registration profile plus every audit request you've submitted (with status counts) and your watched companies — in a single call, so you don't have to store request_ids yourself across sessions.

6. Watch a company for re-audits:

   POST https://agentnativeoffers.com/api/agent/watch
   Authorization: Bearer ano_...
   Content-Type: application/json

   {"slug": "composio"}

   Use a leaderboard slug from /api/audits/index.json. You'll be notified at your registered contact_email when that company is re-audited. DELETE the same endpoint with the same body to unwatch. Your watched list comes back in GET /api/agent/me.

7. See your compounding value:

   GET https://agentnativeoffers.com/api/agent/digest
   Authorization: Bearer ano_...

   Returns how much the companies you watch have improved since you started watching them — net points gained, per-company deltas, and completed requests. The longer you engage, the more this signal is worth.

## MCP server (recommended for agent stacks)

Instead of calling the REST endpoints directly, you can connect AUDIE as a remote MCP server and use it as a set of tools:

   Endpoint: https://agentnativeoffers.com/mcp
   Transport: Streamable HTTP (JSON-RPC 2.0; POST a JSON-RPC message)

Tools:
- No auth: `list_audits`, `get_audit`, `watch_stats`
- Needs api_key: `register_agent` (issues the key), `request_audit`, `check_audit_request`, `my_audit_history`, `watch_company`, `my_digest`

Pass the api_key as a tool argument, or send it as `Authorization: Bearer ano_...` on the MCP request. `register_agent` lets an agent bootstrap a key without leaving the MCP session.

## Staleness & demand signals (no auth)

- Every audit record carries `reaudit_due` — an absolute date (audit_date + 180 days). Compare it to today to decide when a score is stale and worth re-requesting.
- GET https://agentnativeoffers.com/api/watch-stats returns anonymous aggregate watcher counts per company (`{"companies":[{"slug":"...","watchers":N}]}`) — a public demand signal. Individual watch lists are private; only totals are exposed.

## Limits & terms

- Registration: instant, free, max 60/hour platform-wide.
- Audit requests: max 10 per registration per 24h. Audits are free while the public leaderboard is in beta; performed by a human-supervised agent, typical turnaround 2–5 business days.
- Identity-assertion flows (ID-JAG) and key revocation: not yet supported. Planned. Treat keys as low-privilege; they can only create audit requests and read their own.
- Privacy: we store agent_name, provider, optional contact email, and request contents. Nothing else. Data is never sold; CC BY-NC 4.0 applies only to published audit scores.

## Errors

- 401 invalid_token — register again at /api/agent/auth
- 422 invalid_request — company and website (http/https URL) are required
- 429 rate_limited — message includes the window

## Human contact

aionestopshop25@gmail.com — Agent Native Offers, framework from the book THE AGENT SALE (2026).