Authentication

The Namefi API supports three authentication methods. Which one you need depends on the operation you are calling.

OpenAPI auth schemes

The published OpenAPI now exposes all three auth schemes globally:

• apiKeyAuth -> x-api-key
• siwe -> x-namefi-siwe-token
• eip712Signer -> x-namefi-signer
• eip712Signature -> x-namefi-signature
• eip712PrimaryType -> x-namefi-eip712-type

That global security block is descriptive, but it is not enough to infer per-operation auth mode by itself. In practice, operations still fall into one of four effective auth modes.

Auth modes by operation

API key authentication

The simplest authentication method. Works for all operations including DNS record creation, updates, deletes, domain registration, and parking.

Important: The API key inherits permissions from the wallet that generated it. To manage DNS records for a domain, generate the key from the wallet that owns that domain's NFT.

Direct HTTP usage (no SDK needed)

For AI agents, scripts, and quick integrations, pass the API key directly as an HTTP header:

curl -X POST "https://api.namefi.io/v-next/dns/records" \
  -H "x-api-key: nfk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"zoneName":"example.com","type":"A","name":"@","rdata":"1.2.3.4","ttl":300}'

SDK usage

Create a client with an API key:

import { createNamefiClient } from '@namefi/api-client';

const client = createNamefiClient({
  authentication: {
    apiKey: process.env.NAMEFI_API_KEY!,
    type: 'API_KEY',
  },
  logger: true,
});

Generate an API key

• API keys management page

EIP-712 authentication

EIP-712 signs a typed-data envelope per request. The current source of truth for the domain and types is the live helper API:

• GET /v-next/eip712/domain?chain=1
• GET /v-next/eip712/types
• GET /v-next/eip712/types-for-method?method=toggleDomainParking

If you use @namefi/api-client with type: 'EIP712', the client handles envelope construction and signing automatically.

If you are building a raw integration, see the EIP-712 Signing guide.

SIWE authentication

SIWE uses a short challenge-response flow:

1. GET /v-next/siwe/allowed-chains
2. GET /v-next/siwe/nonce
3. GET /v-next/siwe/message
4. Sign messageString with ERC-191 personal_sign
5. POST /v-next/siwe/verify
6. Reuse the returned x-namefi-siwe-token

If you use @namefi/api-client with type: 'EIP712', the client bootstraps SIWE automatically for protected non-EIP-712 operations.

For manual flows and raw HTTP examples, see the SIWE Authentication guide.

Signer-neutral preparation

If you want to prepare auth payloads without wiring a signer into the client, use the public namefi-skills helpers.

The canonical entrypoint is:

bun .rulesync/skills/namefi-api/scripts/prepare-auth-request.ts \
  --env dev \
  --operationId toggleDomainParking \
  --payload '{"normalizedDomainName":"march1104.gl","enableParking":true,"overrideExistingRecords":false}'

That script inspects the operation and returns one of:

• a no-auth request template
• a SIWE prep flow with messageString and verify payload
• an EIP-712 prep flow with live domain, types, typed data, and header templates

The returned payload can then be signed by any external skill, wallet, or MCP.

For the full canonical prepare-only workflow, see Prepare Auth Requests.