# Authentication



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

| Method      | Headers                                                         | Typical use                                 |
| ----------- | --------------------------------------------------------------- | ------------------------------------------- |
| **API Key** | `x-api-key`                                                     | Simplest option, works for all operations   |
| **EIP-712** | `x-namefi-signer`, `x-namefi-signature`, `x-namefi-eip712-type` | DNS writes, parking, domain registration    |
| **SIWE**    | `x-namefi-siwe-token`                                           | Protected reads that do not require EIP-712 |

OpenAPI auth schemes [#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 [#auth-modes-by-operation]

| Auth mode       | Meaning                                                                 | Example operations                                         |
| --------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------- |
| `eip712`        | Requires a fresh EIP-712 signature on the request body                  | `toggleDomainParking`, `createDnsRecord`, `registerDomain` |
| `siwe-required` | Requires a SIWE session token                                           | `getUserDomains`, `getUserOrders`, `getOrder`              |
| `siwe-optional` | Can be anonymous, but may use SIWE when you want authenticated behavior | `checkAvailability`, `registerDomainX402`                  |
| `none`          | No authentication required                                              | `getSuggestions`, `getSiweNonce`, `getEip712Domain`        |

API key authentication [#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) [#direct-http-usage-no-sdk-needed]

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

```bash
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 [#sdk-usage]

Create a client with an API key:

```ts
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 [#generate-an-api-key]

* [API keys management page](https://namefi.io/profile?tab=api-keys)

<video src="/generate-api-key.mp4" style="{ width: '100%', borderRadius: '8px' }">
  Your browser does not support the video tag.
</video>

EIP-712 authentication [#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](/docs/02a-eip712-signing).

SIWE authentication [#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](/docs/02b-siwe-authentication).

Signer-neutral preparation [#signer-neutral-preparation]

If you want to prepare auth payloads without wiring a signer into the client, use the public [namefi-skills](https://github.com/d3servelabs/namefi-skills) helpers.

The canonical entrypoint is:

```bash
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](/docs/02c-prepare-auth-requests).