API Documentation

All endpoints require HMAC-SHA256 authentication. Generate API keys from the admin dashboard.

Authentication

Every request to /api/v1/* must include three headers:

X-Api-Key-IdYour API key ID (from admin dashboard)

X-TimestampUnix timestamp in milliseconds (must be within 5 minutes)

X-SignatureHMAC-SHA256(secret, timestamp + body)

// Signature generation (Node.js)

const crypto = require('crypto');

const timestamp = Date.now().toString();

const body = JSON.stringify({ hexContent: "0A1B..." });

const signature = crypto

.createHmac('sha256', secretHash)

.update(timestamp + body)

.digest('hex');

5-minute replay window

60 req/min, 5000 req/hr per key

Endpoints

POST/api/v1/transponder/decode

Decode Transponder Dump

Submit a hex-encoded binary dump for full transponder analysis. Returns chip identification, memory mapping, ISK extraction, clone readiness assessment, and decoded fields.

Request Body

Field	Type	Required	Description
hexContent	string		Hex-encoded binary content of the transponder dump
fileName	string	—	Original filename (helps with chip detection heuristics)
chipFamily	string	—	Hint: PCF7953, NCF29A1, PCF7945, etc.

Response

Chip identification, memory regions, ISK if found, clone readiness score, decoded EEPROM/EROM fields.

POST/api/v1/transponder/analyse

Static Analysis

Run static analysis on a hex dump — entropy measurement, crypto detection, string extraction, chip fingerprinting.

Request Body

Field	Type	Required	Description
hexContent	string		Hex-encoded binary content
fileName	string	—	Original filename

Response

Entropy scores, detected crypto patterns, extracted strings, chip family fingerprint matches.

GET/api/v1/decoder/rules

List Decoder Rules

Retrieve active local decoder rules. These are pattern-matching rules learned from previous decodes — VIN offsets, ISK patterns, hex signatures, CRC checks.

Response

Array of active decoder rules with kind, pattern, confidence, and hit count.

POST/api/v1/decoder/rules

Create Decoder Rule

Add a new decoder rule to the pattern engine. Rules are automatically applied to future decodes.

Request Body

Field	Type	Required	Description
kind	string		Rule type: vin_offset, isk_offset, hex_signature, part_number, byte_pattern, crc_check
pattern	string		The match pattern (regex for hex_signature, offset spec for vin_offset/isk_offset)
fileKind	string	—	Restrict to file kind: eeprom, erom, full, flash
extractAs	string	—	Label for extracted data: vin, isk, part_number, etc.
notes	string	—	Human-readable notes about this rule

Response

Created rule object with ID.

GET/api/v1/mcu/pcf7953

PCF7953 Reference

Retrieve PCF7953 doctrine data — memory maps, programming procedures, security regions.

Response

PCF7953 doctrine object with memory layout, security zones, programming protocols.

GET/api/v1/health

Health Check

No auth required. Returns service status, capabilities list, supported chips, and live data counts. Other Lock50 services poll this to discover what's available.

Response

Service status, version, capabilities array, supported chips, data counts per table.

POST/api/v1/lookup

Vehicle Lookup

Brain-to-brain query: given a brand/model/chipFamily, returns everything the transponder service knows — chip mappings, ECU dump references, EEPROM specs, immo PIN locations, transponder files, and active decoder rules.

Request Body

Field	Type	Required	Description
brand	string	—	Vehicle brand: BMW, Jaguar, Land Rover, Audi, etc.
model	string	—	Model name or partial match: E90, XF, Evoque
chipFamily	string	—	Chip family: PCF7953, NCF29A1, PCF7945

Response

Transponder catalogue matches, ECU dumps, EEPROM chip specs, immo PIN locations, transponder files, active decoder rules.

POST/api/v1/catalogue

Reference Catalogue

Query any of the 4 reference data tables directly. Filter by brand, chipFamily, with pagination.

Request Body

Field	Type	Required	Description
table	string		Table to query: transponder, ecu, eeprom, immo
brand	string	—	Filter by brand
chipFamily	string	—	Filter by chip family
limit	number	—	Max results (default 100, max 500)

Response

Array of matching catalogue entries.

Status Codes

200Success

400Bad Request

401Unauthorized

403Forbidden

429Rate Limited

500Server Error

501Not Implemented