ACCUZ® Brand Guard™ / SDK 1.3.3 / HTTP API v1

First live request and ownership

Start here

Prepare the first live request

Run the simulator first: node reference/node-server.mjs. Open the displayed loopback URL, choose a synthetic tap and switch languages. No token or tag is used. All URLs and receipt data below are synthetic; never submit these examples to a real verification service.

Use Node.js 22.12 or later with npm for the complete workflow (validated with 24.16). Node 20 supports the dependency-free simulator and npm test only; the locked native tools need Node 22 and Wrangler needs 22.12. npm test runs without dependencies. npm run test:full installs the locked native tooling and runs genuine workerd/SQLite plus Node/DOM checks on Windows or POSIX. It requires package-registry access on the first run. Output stays in test-output/ inside the extracted SDK.

Website approval and old proof files

Ask the administrator to inspect the exact HTTPS origin in the intended environment and tenant. Register and verify each hostname separately, for example website.example and verify.website.example. Paths on the same hostname share its ownership approval. A new connection can reuse an origin already approved there; credentials remain bound to their connection. A new SKU alone does not require a new ownership file, token or compatible encoding.

When moving environment or tenant, check approval in the target. If it is already approved, use that state. Otherwise obtain the current public proof and its exact URL from the administrator. A normal site typically publishes the provided .well-known file; a WordPress installation may use the proof endpoint supplied by the console. Do not invent a filename or change the payload.

For each verification compare installationId and challenge with the current registration. Correcting or registering again may issue another challenge. Keep a file while the registration, re-verification or installation still depends on it. Delete an old file only after that registration is retired and no other use remains. Deleting the file does not revoke an already saved API approval.

Terms used in the setup sheet

NFC first hop
The exact first website path opened by the physical tag. A later redirect does not change what was written.
Writer
The authorized tool that writes and reads back the tag. A new exact path may require a new immutable encoding.
SDM
Secure Dynamic Messaging: the chip creates dynamic authentication data in the tag URL.
encodingVersionId
The administrator-issued immutable identifier for the approved chip and URL template.
SKU mode
Your website matches the complete authenticated SKU against its trusted product catalog.
Path mode
Use an approved same-origin product or Item-specific path returned by the verified receipt.
UID-based record lookup
Your authorized staff or backend associates a verified chip UID with a record in your system. A visitor request or replay does not create that association.
Item ID
A platform identity for one physical Item, learned from the receipt; no list is required to begin integration.

Configure entries and localized pages

Begin with config/site.example.json: one approved /v entryPath, one assigned encodingVersionId and one server secret BRANDGUARD_VERIFICATION_TOKEN. Copy it to ignored config/site.local.json and replace the non-secret placeholders. encodingVersionId is 1–32 visible ASCII characters, not a fixed-length or GUID format. Token values start with bgci_ and belong only in server secret storage, never this config, browser code or the setup form.

Advanced only: config/advanced-multi-entry.example.json uses entrypoints and wrangler.advanced.toml for two approved entries, /v and /scan/verify, with separate named bindings. Do not combine entrypoints with the single-entry keys. An exact path selects one encoding and credential before the SKU is known. Do not trial alternatives. Compatible SKUs may share one entry and encoding. A different encoding can use a distinct approved exact entry. Duplicate, ambiguous, reserved or cross-origin entries fail preflight.

Accept-Language weights choose the first registered language. The authenticated product page family is frozen for this operation; language switching retains __bg_receipt. Item-specific paths and path mode have priority. Legacy string paths still work. Other products and later mapping changes cannot read this receipt.

{
  "packageVersion": "1.3.3",
  "httpApiVersion": "v1",
  "apiOrigin": "https://ASSIGNED-API-ORIGIN.example",
  "websiteOrigin": "https://website.example",
  "mode": "sku",
  "catalog": {
    "MODEL-A": {
      "defaultLanguage": "en",
      "pages": {
        "en": "/en/products/model-a.html",
        "zh": "/zh/products/model-a.html",
        "ja": "/ja/products/model-a.html",
        "ko": "/ko/products/model-a.html"
      }
    },
    "MODEL-B/R2": {
      "defaultLanguage": "en",
      "pages": {
        "en": "/en/products/model-b.html",
        "zh": "/zh/products/model-b.html",
        "ja": "/ja/products/model-b.html",
        "ko": "/ko/products/model-b.html"
      }
    }
  },
  "associations": {},
  "regionEnabled": false,
  "timeZone": "UTC",
  "language": "en",
  "defaultLanguage": "en",
  "entryPath": "/v",
  "encodingVersionId": "REPLACE_FROM_NON_SECRET_HANDOFF"
}

Executable Cloudflare setup and deployment · Five ordinary DNA examples

Anonymous reachability probe

Replace api.example.invalid with the exact origin assigned by the administrator. Send the empty JSON without a token. Expect HTTP 401 with JSON not_authorized. This confirms anonymous traffic reached authentication; it does not validate an encoding, token, tag or seal. HTML, a redirect or 400 from a gateway needs investigation before live tap testing.

curl

API_ORIGIN='https://api.example.invalid'
curl -i --request POST "$API_ORIGIN/api/customer/v1/verifications" \
  --header 'Content-Type: application/json' --data '{}'

PowerShell

$apiOrigin = 'https://api.example.invalid'
try {
  $r = Invoke-WebRequest -UseBasicParsing -Uri ($apiOrigin + '/api/customer/v1/verifications') -Method Post -ContentType 'application/json' -Body '{}'
  $r.StatusCode; $r.Content
} catch {
  $response = $_.Exception.Response
  if (-not $response) { throw }
  [int]$response.StatusCode
  if ($_.ErrorDetails.Message) { $_.ErrorDetails.Message }
  elseif ($response.PSObject.Methods.Name -contains 'GetResponseStream') {
    $reader = New-Object IO.StreamReader($response.GetResponseStream())
    try { $reader.ReadToEnd() } finally { $reader.Dispose() }
  }
}

One complete synthetic exchange

The ordinary NTAG 424 DNA example below has no electronic seal: seal.supported=false and seal.state=null. samples/ordinary-dna.json contains all five decisions (valid, replay, invalid_signature, unknown_tag, policy_rejected), each with its complete synthetic request and response. The tag URL, headers and body below come directly from that file. Capture a real tag URL at your own approved first hop without changing query order, case or percent encoding. Live settings and the real server secret are supplied separately. acceptedAt and decidedAt are independent valid timestamps; they are not required to be identical.

Tag URL

https://website.example/v?h=00000000-0000-4000-8000-000000000001&e=11111111111111111111111111111111&c=0000000000000001

Request

POST https://api.example.invalid/api/customer/v1/verifications
Authorization: Bearer bgci_SYNTHETIC_EXAMPLE_ONLY
Content-Type: application/json
Idempotency-Key: synthetic-ordinary-valid

{
  "encodingVersionId": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
  "tapUrl": "https://website.example/v?h=00000000-0000-4000-8000-000000000001&e=11111111111111111111111111111111&c=0000000000000001"
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "receipt": {
    "verificationId": "a0000000000000000000000000000000",
    "result": "valid",
    "decidedAt": "2026-11-16T03:15:45Z",
    "acceptedAt": "2026-11-16T03:15:45Z",
    "uid": "04AABBCCDDEE01",
    "itemId": "BG-SYNTH-000001",
    "counter": 12,
    "acceptedVerificationCount": 1,
    "seal": {
      "supported": false,
      "state": null
    },
    "encodingVersionId": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
    "clientRequestId": null,
    "sku": "MODEL-A"
  },
  "recovered": false,
  "currentEligibility": {
    "eligible": true,
    "checkedAt": "2026-11-16T03:15:45Z"
  }
}

Diagnose without leaking the request

A complete HTTP 200 with invalid required data is terminal unconfirmed, with no automatic re-verification. A body transport interruption is different: the complete receipt was not received, so the same operation can recover. Malformed optional routing metadata goes to the generic result without erasing a valid decision.

Read httpStatus, diagnosticCode and correlationId from the reference server. 401 means the verification credential was rejected; inspect missing, wrong-environment, expired or revoked credentials. 403 means an integration, origin or scope is not permitted. 409 means a request conflict. A bad bgci_ prefix or missing secret binding is a configuration error before any API call. Share the generated support reference; never share token values, full tap URLs, IPs or upstream private bodies.

From 1.3 / 1.3.1, change queues that kept raw requests after 401/403: 1.3.3 clears sensitive pending data and ends that submission. Correct the settings and obtain a fresh physical tap. Network uncertainty, 202, 429 and 503 still use the original key/body/origin. No output from this package is evidence that a customer website or physical tag has been accepted.