Authentication (SIWE)

Bloomfilter uses SIWE (Sign-In With Ethereum) for authentication. Your wallet is your identity — no username, no password, no email.

When you need auth

Most endpoints are public. Authentication is required for:

DNS management — GET/POST/PUT/DELETE /dns/{domain}
Account info — GET /account, GET /account/domains, GET /account/transactions
Session revocation — POST /auth/revoke

Authentication flow

Get a nonce

curl https://api.bloomfilter.xyz/auth/nonce

{
  "nonce": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "domain": "api.bloomfilter.xyz",
  "uri": "https://api.bloomfilter.xyz",
  "chainId": 8453,
  "version": "1",
  "expiresIn": 300
}

Construct and sign a SIWE message

Build an EIP-4361 message using the nonce, then sign it with your wallet:

import { createSiweMessage } from "viem/siwe";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount("0xYOUR_PRIVATE_KEY");
const message = createSiweMessage({
  address: account.address,
  chainId: 8453,
  domain: "api.bloomfilter.xyz",
  nonce: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  uri: "https://api.bloomfilter.xyz",
  version: "1",
  issuedAt: new Date(),
});

const signature = await account.signMessage({ message });

Verify and get tokens

curl -X POST https://api.bloomfilter.xyz/auth/verify \
  -H "Content-Type: application/json" \
  -d '{"message": "api.bloomfilter.xyz wants you to sign in...", "signature": "0xabc..."}'

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "rt_a1b2c3d4...",
  "expiresIn": 3600,
  "walletAddress": "0x1234567890abcdef1234567890abcdef12345678"
}

Use the token

Include the access token in the Authorization header:

curl https://api.bloomfilter.xyz/dns/example.io \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Token lifecycle

Token	Lifetime	Notes
Access token	1 hour	JWT, included in `Authorization: Bearer` header
Refresh token	30 days	Used to get a new access token without re-signing
Nonce	5 minutes	One-time use, must be consumed within `expiresIn` seconds

Refreshing tokens

When your access token expires, use the refresh token:

curl -X POST https://api.bloomfilter.xyz/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "rt_a1b2c3d4..."}'

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "rt_new_token..."
}

Revoking sessions

To invalidate all active sessions:

curl -X POST https://api.bloomfilter.xyz/auth/revoke \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

This revokes all access and refresh tokens for your wallet.