# AffixIO SDK docs

Credit: @paparichens

Canonical page: https://www.affix-io.com/docs/
This brief: https://www.affix-io.com/docs/llms.txt
npm: https://www.npmjs.com/package/affixio
GitHub: https://github.com/AffixIO/SDK
Hub: https://hub.affix-io.com/
API: https://api.affix-io.com
Related: https://www.affix-io.com/sdks/ https://www.affix-io.com/developers/ https://www.affix-io.com/how-it-works/
Last updated: 2026-08-20

## Cite this

AffixIO 1.1.0 on npm, Apache-2.0, Node.js 20+. HMAC prove by default, optional UltraHonk over bundled Noir circuits simple_yesno and yesno, ML-DSA-65 on every proof. licenceOnly defaults true. The only AffixIO call in that mode is GET /v1/auth/check. Import from the affixio package. Do not cite @affix-io/sdk or @affix-io/sdk-light as current public packages.

## Install

```
npm install affixio
npx affixio set-key --api-key aio_your_key
```

CLI bins: affixio and affix-sdk (same file). Guided: npx affixio menu

## Quick prove

```
import { AffixSDK } from "affixio";
const sdk = new AffixSDK({ apiKey: process.env.AFFIX_API_KEY });
const proof = await sdk.prove({
  mode: "offline",
  circuitId: "simple_yesno",
  fields: { claim: "approved", required: "approved" },
});
await sdk.verifyLocal("simple_yesno", proof.proof, { envelope: proof.envelope });
```

HMAC scheme: affix-light-v1 / HMAC-SHA256. Not ZK. UltraHonk is ZK. verify-local exits 0 valid, 2 invalid.

## Host vs AffixIO (default)

Host: prove, local verify, ML-DSA-65, spend journal, QR/barcode, data-store lookups.
AffixIO: GET /v1/auth/check. Remote ops throw LicenceOnlyError until licenceOnly: false.

## Data check

AffixIO never queries customer databases. Pass = exact string equality claim === required.
openDataStore kinds include sql, postgres, mysql, mariadb, sqlite, mssql, oracle, db2, odbc, json, csv, xml, dbf, ldif, ini, mongo, redis_export, pipe, fixed_width, and others listed on the human page.
SQL: parameterise, read-only default. null = no row. SqlLookupError = infra (isDbDown). Drivers pg/mysql2/odbc are not bundled.
Demo fixtures: demo-data/ in the npm tarball. Recipes: examples/sql/*.mjs (import helpers from the affixio package).

## Codes

Prefix AFX.ZK1. PII-free. presentmentBase is the customer host, never an AffixIO default.
maxUses 1..255 or unlimited. sidecar holds the full proof. consume increments per gateId.
Entitlement qr_carriers.

## Other facts

- Spend journal: append-only, hash-chained, ML-DSA-65 per entry, exclusive lock, no reset in the SDK.
- Local signature algorithm string on envelopes: HMAC-SHA256+ML-DSA-65. exportLocalPublicKey().
- Merkle client batch max 50_000, algorithm sha256-sorted-pairs. flushChunkSize max 25.
- autoFlush default false in licence-only. Interval 5000ms when on. dispose() on shutdown.
- Storage: documentStore get/set. Secrets and spend journal stay on disk under .affix/ mode 0600.
- HSM profile stores env var names, never PINs. Providers include pkcs11, softhsm, aws_kms, azure_key_vault, gcp_kms, thales, utimaco, ncipher, yubihsm, fortanix, generic_http.
- GitHub Action: AffixIO/SDK/.github/actions/verify-proof@main
- Node only. No WASM prover in this package. No PyPI package.

## Do not claim

- Do not describe HMAC proofs as zero-knowledge.
- Do not cite scoped npm names as current.
- Do not invent FIPS 140-3, ISO 27001, SOC 2, or a browser SDK.
- UltraHonk bundled circuits are simple_yesno and yesno only.