---
title: finddomain.io auth.md
description: How agents authenticate to the Find Domain API — anonymous identity with per-request x402 payment.
canonical: https://finddomain.io/auth.md
last-updated: 2026-08-27
---

# finddomain.io auth.md

You are an agent. This service supports **agentic registration** in its
simplest possible form: the `anonymous` identity type with per-request
x402 payment credentials. Flow: discover → pick method → register (a no-op)
→ pay per request. There are no accounts, API keys, or OAuth grants —
**payment is authentication**.

## Step 1 — Discover

### 1a. Fetch the Protected Resource Metadata

```http
GET https://finddomain.io/.well-known/oauth-protected-resource
```

Returns `resource`, `authorization_servers` (this same origin),
`scopes_supported`, and `bearer_methods_supported`. The scopes
(`domain:suggest`, `domain:status`, `domain:demo`) are informational
labels for the API's capabilities — access is gated per request by
payment, never by scope, and no token ever carries them.

### 1b. Fetch the Authorization Server metadata

```http
GET https://finddomain.io/.well-known/oauth-authorization-server
```

The `agent_auth` block declares everything that matters here:
`identity_types_supported: ["anonymous"]`,
`credential_types_supported: ["x402-payment"]`, `claim_uri`,
`register_uri` (this document), and `skill`. Note
`grant_types_supported` is an empty list: the `token_endpoint` issues no
tokens and answers every request with `unsupported_grant_type` pointing
back here.

## Step 2 — Pick a method

Only `anonymous` is supported. No user identity is ever asserted to this
service: there is no `identity_assertion` (ID-JAG), no `service_auth`,
no verified-email flow, and no claim ceremony. If your framework
requires choosing a registration method, choose `anonymous`.

## Step 3 — Register

Anonymous registration is **implicit and stateless** — there is no
registration endpoint to call, no `registration_id`, and nothing to
store. Provisioning is out of band: hold an EVM wallet funded with USDC
on Base (`eip155:8453`) that can sign EIP-3009 transfer authorizations.

## Step 4 — Authenticate each request with x402

1. Call any paid endpoint with no credentials, e.g.
   `GET https://finddomain.io/suggest?query=tea`
2. The service replies `402 Payment Required`; the `payment-required`
   header carries x402 v2 requirements (amount, asset, network, payTo).
3. Sign an EIP-3009 USDC authorization matching the requirements and
   retry with the `payment` header — or pass it as the
   `payment_signature` tool argument on the MCP server at
   `https://finddomain.io/mcp`. x402 client SDKs do steps 2–3
   automatically (see [skill.md](https://finddomain.io/skill.md)).

## Step 5 — Use the API

- `GET /suggest?query=TERM` — domain name suggestions ($0.005)
- `GET /status?domain=DOMAIN` — registry availability check ($0.020)
- `GET /status?domain=DOMAIN&scope=estimate` — DNS estimate ($0.005)
- `GET /demo?query=TERM` — free, 3 queries/day per IP, no payment
- Machine-readable spec: [openapi.json](https://finddomain.io/openapi.json)

## Errors

- `402` with `payment-required` header — sign and retry (Step 4).
- `400 unsupported_grant_type` / `unsupported_response_type` from the
  OAuth endpoints — expected; this service issues no grants, use x402.
- `429` on `/demo` — free-tier limit reached; use paid endpoints.

## Revocation

Nothing to revoke: every credential is a single-use payment
authorization that expires 60 seconds after signing. No long-lived
credential exists to store, rotate, or leak.