FlareHQ API Authentication: Keys, Headers, and Errors

Every request you make to the FlareHQ API must be authenticated. Server-to-server calls authenticate with an API key sent in the x-api-key header; browser dashboard sessions authenticate with an HTTP-only cookie. This page explains how to obtain your key, how to attach it to requests, and what to do when authentication fails.

Key types

FlareHQ issues API keys in the format arc_live_<48-hex-chars> — from merchant email verification (POST /api/merchant/verify, shown once) or from service-key provisioning (POST /api/keys). The same x-api-key header mechanism accepts merchant keys, internal service keys, and — on routes that support them — merchant (merchant_token) or consumer (consumer_token) session cookies.

API Key

Prefixed arc_live_.... Used for all server-side API calls — creating checkout sessions, initialising payments, managing webhooks, and anything that touches sensitive data. Never expose this key in browser code, public repositories, or client-side bundles.

Dashboard session

An HTTP-only merchant_token cookie set by POST /api/merchant/login (7-day JWT). Browser dashboard calls authenticate with this cookie instead of a key — it is never pasted into headers or client-side JavaScript by hand.

Generating your keys

Your primary API key is issued when you verify your merchant email with POST /api/merchant/verify — it is returned once in that response (arc_live_...) and never shown again. Service keys are provisioned via POST /api/keys. Store whichever key you use in a secrets vault immediately.

Passing your key in requests

API key header (recommended)

Pass your API key in the x-api-key header on every server-side request:

x-api-key: arc_live_...

cURL example

curl -X POST https://flarehq.xyz/api/payments/initialize \
  -H "x-api-key: arc_live_9f3e..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "10.00",
    "currency": "USDC"
  }'

SDK initialisation

When you use the @flarehq/sdk, pass your API key once at initialisation time. The SDK automatically attaches it to every outbound request — you don’t need to set headers manually.

src/lib/flarehq.ts

import { FlareHQ } from '@flarehq/sdk';

export const flarehq = new FlareHQ({
  apiKey: process.env.FLAREHQ_SECRET_KEY!,   // arc_live_...
  environment: 'production',
  chain: {
    id: 5042,
    rpcUrl: process.env.ARC_RPC_URL,
  },
});

Always read your key from an environment variable — never hardcode it as a string literal in source files. See Best practices below.

Production vs. test environments

Production API activity settles on Arc Mainnet (chain ID 5042) in real USDC — real funds move. Arc Testnet (chain ID 5042002) is available as a development/test environment using test USDC from faucet.circle.com (select ARC-TESTNET). Keys are issued in the arc_live_... format whether they belong to a merchant (POST /api/merchant/verify) or an internal service integration (POST /api/keys).

// Production (Arc Mainnet)
const flarehq = new FlareHQ({ apiKey: 'arc_live_...', environment: 'production', ... });

// Testnet development only
const flarehqTest = new FlareHQ({ apiKey: 'arc_live_...', environment: 'testnet', ... });

Authentication errors

When a request fails due to an authentication problem, the API returns a JSON error body alongside an HTTP error status. The table below covers the most common cases:

HTTP Status	Error	Cause	Resolution
`401 Unauthorized`	`Authentication required`	No `x-api-key` header was sent, or the key is malformed.	Check that your header is `x-api-key: arc_live_...` with no extra characters.
`401 Unauthorized`	`Invalid API key`	The key doesn’t match any active key in your account.	Verify the key was copied correctly and hasn’t been revoked.
`403 Forbidden`	`Invalid or deactivated API key`	The key matched a revoked/deactivated record, or the merchant is unverified/inactive.	Verify the merchant is active and verified, or generate a replacement key.
`429 Too Many Requests`	`Rate limit exceeded`	You’ve exceeded the API rate limit for this key.	Back off and retry after the `Retry-After` header interval.

Example 401 response

{
  "success": false,
  "error": "Authentication required. Provide a valid API key in the x-api-key header."
}

Example 429 response

{
  "success": false,
  "error": "Rate limit exceeded. Please retry after 30 seconds."
}

Rotating and revoking keys

You can rotate or revoke a key at any time — revoking it deactivates the record, and all requests using that key immediately return 401/403. Generate a replacement key before revoking the old one to avoid downtime.

Set a recurring reminder to rotate your production keys every 90 days as a security hygiene measure, even if you don’t suspect any compromise.

Best practices

Follow these rules to keep your API keys secure throughout your project lifecycle:

Store keys in environment variables

Always read keys from environment variables (process.env.FLAREHQ_SECRET_KEY) rather than inlining them as string literals. Use .env.local locally and your hosting provider’s secrets manager in production.

Never commit keys to source control

Add .env.local and any other env files to your .gitignore before your first commit. Use a tool like git-secrets or a pre-commit hook to scan for key patterns before they reach your repository.

.gitignore

# Environment files
.env
.env.local
.env.*.local

Keep API keys server-side only

Your API key must never appear in browser-executed JavaScript. In Next.js, only import your flarehq client inside Server Components, Route Handlers, or Server Actions — never in 'use client' components.

Use separate keys per environment

Maintain distinct key pairs for development, staging, and production. This limits the blast radius of any accidental exposure and makes it easy to rotate a single environment’s credentials without affecting others.

Rotate keys regularly

Rotate your production API key on a routine schedule (every 60–90 days is a common standard) and immediately any time you suspect it may have been compromised.

Get Started

Payments

x402 Protocol

Agentic Finance

Merchant Platform

Consumer Payments

Developer Guide

FlareHQ API Authentication: Keys, Headers, and Errors

Key types

API Key

Dashboard session

Generating your keys

Passing your key in requests

API key header (recommended)

cURL example

SDK initialisation

Production vs. test environments

Authentication errors

Example 401 response

Example 429 response

Rotating and revoking keys

Best practices

​Key types

API Key

Dashboard session

​Generating your keys

​Passing your key in requests

​API key header (recommended)

​cURL example

​SDK initialisation

​Production vs. test environments

​Authentication errors

​Example 401 response

​Example 429 response

​Rotating and revoking keys

​Best practices

Key types

Generating your keys

Passing your key in requests

API key header (recommended)

cURL example

SDK initialisation

Production vs. test environments

Authentication errors

Example 401 response

Example 429 response

Rotating and revoking keys

Best practices