Wallet authentication

Authentication and authorization are separate. A provider credential identifies the integration; a controller authorization proves that a wallet may mutate a controller-owned mapping.

Resolver requests: provider or Free API key

Production wallets use an approved provider credential. Prototype integrations may use a Free API key, which is accepted only by POST /v1/resolve.

Authorization: Bearer <provider-or-free-api-key>
Content-Type: application/json

• Approved provider keys: 120 resolver requests per minute per provider.
• Free API keys: 10 requests per minute and 100 per UTC day.
• HTTP 401 means the credential is absent, invalid, revoked, or not approved.
• HTTP 429 includes Retry-After when a limit is reached.

Controller authorization for mutations

Registration, updates, suspension, removal, and native-name management require an approved provider plus controller authorization. A provider key is not proof of ownership, and a controller wallet is not a provider credential.

Authorization: Bearer <approved-provider-key>
X-Controller-Wallet: 0xController…
X-Controller-Authorization: <signed authorization payload>
Idempotency-Key: register-request-123

The exact controller authorization payload depends on the configured authorization mode. Keep it in the wallet signing flow; never ask the user to paste a private key into the integration.