BleuSite badge: agent integration guide ======================================= Machine-readable guide for AI agents automating the BleuSite badge self-serve flow (issue #370, #402). All endpoints are on the badge-verify worker, served at https://bleusite.ca/badge/* via a thin proxy in the customer's Cloudflare zone; the backend hostname (badge-backend.aptu.dev) is secret-gated and is not a public surface. Flow ---- 1. POST /badge/request { "domain": "example.ca", "neq": "1143427633" } -> 200 { "wellKnownUrl": "https://example.ca/.well-known/bleusite-badge/" } curl -s -X POST https://bleusite.ca/badge/request \ -H 'content-type: application/json' \ -d '{"domain":"example.ca","neq":"1143427633"}' The NEQ must be an active Registraire des entreprises Quebec (REQ) enterprise. Challenges: 24h TTL, max 5 pending per domain, 10 requests/hour/IP. Optional `method` field chooses the domain-control challenge (#84): `"well-known"` (default) or `"dns"`. With `"dns"` the response replaces `wellKnownUrl` with a `dnsRecord` descriptor: -> 200 { "dnsRecord": { "name": "_bleusite-badge.example.ca", "type": "TXT", "value": "" }, "nonce": "" } 2a. Well-known method: serve the exact nonce as the body (exact trimmed match) at the wellKnownUrl over HTTPS. 2b. DNS method: publish a TXT record at host `_bleusite-badge.` (e.g. `_bleusite-badge.example.ca`) whose value is the exact nonce. Quoted or RFC 1035 split-chunk values ("abc" "def") are normalized before comparison. 3. POST /badge/verify { "domain": "example.ca", "nonce": "" } -> 200 { "uuid": "...", "badgePath": "/badge/.svg" } curl -s -X POST https://bleusite.ca/badge/verify \ -H 'content-type: application/json' \ -d '{"domain":"example.ca","nonce":""}' The server checks the method recorded at request time. Well-known: it fetches the well-known URL https-only (no redirects, 5s timeout, 4096-byte cap) and requires an exact trimmed body match. DNS: it queries TXT `_bleusite-badge.` via the Cloudflare DNS-over-HTTPS JSON API (same timeout and no-redirect hardening) and requires any returned TXT string to equal the nonce exactly. Both methods share the same TTL, tombstone, pending cap, and rate limits. Error semantics --------------- - 400: {"error": "", "detail": "..."} -- validation failures with a named reason. - 404: unknown or expired challenge (nonce never issued or past the 24h TTL). - 409: challenge already consumed (verified once; tombstone kept 24h so replays are rejected). Badge embed ----------- - SVG image: GET /badge/.svg - Click-through facts page: GET /badge/ - Human self-serve page: GET /badge/ (add ?lang=en for English; French is the default) Registry facts only ------------------- Badge facts come from public registries only (REQ open data, and the RBQ licence register when a licence is recorded). No endorsement is implied; content is licensed CC BY-NC-SA 4.0. Issuance is free.