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

Two different dashboard credentials can authorize POST /v1/resolve. They are not the same product:

• Provider API key — create under Wallet Provider → API keys after approval. Use for production wallets. Higher rate limits. Also required for mutation and namespace routes (with controller auth where applicable).
• Free API key — create under Free API with no approval. Prototypes and testing only. Accepted only by POST /v1/resolve. Lower limits. Cannot mutate the registry or manage namespaces.

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.

Dashboard map: Which API key do I use?.

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.