Custom identifiers

Custom identifiers bring your own signals into every evaluation: a license ID, an account number, a contract reference from your own records. You hash each value with a secret only you hold, and AbuseZero checks the hash against your workspace's full claim history without ever receiving the raw value. Register each identifier and the version of the secret you hash it with before you send it. See Custom identifiers for the concept and Send identifiers for hashing.

Examples on this page use a server client:

import { AbuseZero } from "abusezero/server";

const abusezero = new AbuseZero({ key: process.env.ABUSEZERO_SECRET_KEY!, outage: "throw" });

The custom identifier objectCopy Anchor Link

{
  "object": "custom_identifier",
  "id": "cid_7d3b1f9a-4e2c-4a8b-b5d6-2f0e8c4a6b19",
  "key": "license_id",
  "key_version": "2026-10",
  "description": "License ID from our billing system",
  "created_at": "2026-10-29T10:02:41.000Z",
  "updated_at": "2026-10-29T10:02:41.000Z"
}

Each registration covers one key and key_version pair. To rotate the secret behind an identifier, register the same key with a new key_version, then start hashing with the new secret. A hash made with a different secret is a different value, so claims recorded under the earlier version don't match values hashed under the new one.

Register a custom identifierCopy Anchor Link

Also available as abusezero custom-identifiers register in the AbuseZero CLI, abusezero_register_custom_identifier on the AbuseZero MCP server and registerCustomIdentifier() in the AbuseZero Node.js SDK.

Request bodyCopy Anchor Link

ExampleCopy Anchor Link

await abusezero.registerCustomIdentifier(
  {
    key: "license_id",
    key_version: "2026-10",
    description: "License ID from our billing system",
  },
  "register-license-id-2026-10",
);

ResponseCopy Anchor Link

Returns 201.

{
  "object": "custom_identifier"
}

The response confirms the registration. To read its ID, list custom identifiers. A retry with the same Idempotency-Key and body returns the same confirmation.

Once registered, the identifier can be sent in evaluations:

{
  "identifiers": {
    "custom": [
      {
        "key": "license_id",
        "value_hash": {
          "algorithm": "hmac-sha256",
          "key_version": "2026-10",
          "value": "<64 lowercase hex characters>"
        }
      }
    ]
  }
}

The AbuseZero Node.js SDK's createCustomIdentifier builds this object for you. See Send identifiers.

ErrorsCopy Anchor Link

An evaluation that sends a key and key_version pair that isn't registered returns UNSUPPORTED_FIELD, with the message "Register this custom identifier and key version in Developers → Custom identifiers first." For every other code, see REST API errors.

List custom identifiersCopy Anchor Link

Returns registrations, most recently changed first.

Also available as abusezero custom-identifiers list in the AbuseZero CLI, abusezero_list_custom_identifiers on the AbuseZero MCP server and customIdentifiers() in the AbuseZero Node.js SDK.

Query parametersCopy Anchor Link

ExampleCopy Anchor Link

const page = await abusezero.customIdentifiers();

ResponseCopy Anchor Link

Returns 200.

{
  "object": "list",
  "data": [
    {
      "object": "custom_identifier",
      "id": "cid_7d3b1f9a-4e2c-4a8b-b5d6-2f0e8c4a6b19",
      "key": "license_id",
      "key_version": "2026-10",
      "description": "License ID from our billing system",
      "created_at": "2026-10-29T10:02:41.000Z",
      "updated_at": "2026-10-29T10:02:41.000Z"
    }
  ],
  "next_cursor": null
}

Retrieve a custom identifierCopy Anchor Link

Also available as abusezero custom-identifiers get in the AbuseZero CLI, abusezero_get_custom_identifier on the AbuseZero MCP server and call() in the AbuseZero Node.js SDK.

Path parametersCopy Anchor Link

ExampleCopy Anchor Link

const registration = await abusezero.call("/v1/custom-identifiers/cid_7d3b1f9a-4e2c-4a8b-b5d6-2f0e8c4a6b19");

ResponseCopy Anchor Link

Returns 200 with a custom identifier object.

ErrorsCopy Anchor Link

Remove a custom identifierCopy Anchor Link

Removes one key and key_version registration. Evaluations that send that pair afterwards return UNSUPPORTED_FIELD, so stop sending it first.

Also available as abusezero custom-identifiers delete in the AbuseZero CLI, abusezero_delete_custom_identifier on the AbuseZero MCP server and deleteCustomIdentifier() in the AbuseZero Node.js SDK.

Path parametersCopy Anchor Link

ExampleCopy Anchor Link

await abusezero.deleteCustomIdentifier(
  "cid_7d3b1f9a-4e2c-4a8b-b5d6-2f0e8c4a6b19",
  "remove-cid-7d3b1f9a",
);

ResponseCopy Anchor Link

Returns 200. A retry with the same Idempotency-Key returns this same response.

{
  "object": "deleted",
  "id": "cid_7d3b1f9a-4e2c-4a8b-b5d6-2f0e8c4a6b19",
  "deleted": true
}

ErrorsCopy Anchor Link

RelatedCopy Anchor Link