# auth.md — VeriState Agent Authentication & Registration

You are an agent. This service (**VeriState Ground-Truth Oracle**, `https://veristate.xyz`) supports **agentic registration** (discover → register → claim if needed → exchange for an `access_token` → call API → handle revocation) as well as permissionless **HTTP 402 (`x402`) Base USDC** settlement.

## Step 1 — Discover

1. **OAuth Protected Resource Metadata (RFC 9728)**:
   `GET https://veristate.xyz/.well-known/oauth-protected-resource`
   - `resource`: `https://veristate.xyz`
   - `authorization_servers`: `["https://veristate.xyz"]`
   - `scopes_supported`: `["oracle:read", "oracle:verify", "x402:settle", "mcp:tools"]`
   - `bearer_methods_supported`: `["header"]`

2. **OAuth Authorization Server Metadata (RFC 8414 + `agent_auth`)**:
   `GET https://veristate.xyz/.well-known/oauth-authorization-server`
   - `issuer`: `https://veristate.xyz`
   - `agent_auth.skill`: `https://veristate.xyz/auth.md`
   - `agent_auth.register_uri`: `https://veristate.xyz/api/oauth/register`
   - `agent_auth.claim_uri`: `https://veristate.xyz/api/oauth/claim`
   - `agent_auth.revocation_uri`: `https://veristate.xyz/api/oauth/revoke`
   - `agent_auth.identity_types_supported`: `["identity_assertion", "anonymous", "service_auth"]`
   - `agent_auth.identity_assertion.assertion_types_supported`: `["urn:ietf:params:oauth:token-type:id-jag", "verified_email"]`

## Step 2 — Pick a Registration Method

1. **Identity Assertion (`identity_assertion` with `urn:ietf:params:oauth:token-type:id-jag` or `verified_email`)**: Present an audience-bound ID-JAG JWT or verified email assertion to `POST https://veristate.xyz/api/oauth/register`.
2. **Anonymous Agent Registration (`anonymous`)**: Register immediately without prior user session at `POST https://veristate.xyz/api/oauth/register` and optionally complete ownership claim at `https://veristate.xyz/api/oauth/claim`.
3. **Permissionless HTTP 402 (`x402`) Base USDC Settlement**: Sign an `EIP-3009 TransferWithAuthorization` payload on Base Mainnet (`eip155:8453`, USDC `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`, PayTo `0x21B4c6fc23ca4Ab41B272d1BAe5EE3DF1e2F0cdC`) and pass `X-PAYMENT`.

## Step 3 — Register Agent Identity

```bash
curl -X POST https://veristate.xyz/api/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "type": "anonymous",
    "client_name": "my-autonomous-agent",
    "grant_types": ["client_credentials", "urn:ietf:params:oauth:grant-type:jwt-bearer"],
    "scope": "oracle:read oracle:verify x402:settle mcp:tools"
  }'
```

## Step 4 — Exchange Credentials for Access Token

```bash
curl -X POST https://veristate.xyz/api/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "<client_id>",
    "client_secret": "<client_secret>"
  }'
```

## Step 5 — Use Credentials & Handle Revocation

- Send `Authorization: Bearer <access_token>` on API requests to `https://veristate.xyz/api/v1/oracle/*` or `https://veristate.xyz/mcp`.
- To revoke credentials, send `POST https://veristate.xyz/api/oauth/revoke`.