BiomPIN

What is BiomPIN?

BiomPIN is an optional secure sharing system. After processing, BiomAPI can generate a short memorable PIN (lunar-rocket-731904) that links to an encrypted copy of the result. Share it with a colleague, open it in the ESCRS calculator, or retrieve it later.

Data auto-expires after 31 days. No biometry data is stored unencrypted.

---

PIN format

word-word-123456

• Two BIP-39 words — identify the share (stored as primary key in DB)
• Six-digit numeric PIN — the encryption secret (never stored)

The URL format is https://biomapi.com/pin/lunar-rocket-731904 — the full PIN including the numeric suffix is required to decrypt.

---

Security model

Layer	Implementation
Key derivation	Argon2id (memory-hard): time_cost=3, memory_cost=32MB, parallelism=1
Salt	SHA-256(share_id)[:16] — deterministic from the word pair, not stored
Encryption	AES-256-GCM: payload = nonce (12 bytes) + ciphertext
Brute force protection	After 3 wrong numeric PINs, the record is permanently deleted

The server cannot decrypt stored data without the numeric PIN — which is never stored.

---

Generating a BiomPIN

BiomPIN is generated by default on every POST /api/v1/biom/process call. To disable:

curl -X POST .../process \
  -F "file=@report.pdf" \
  -F "create_biompin=false"

In the web UI, use the “Share” toggle before processing.

---

Retrieving data

Via API

GET /api/v1/biom/retrieve?biom_pin=lunar-rocket-731904

Via direct URL

https://biomapi.com/pin/lunar-rocket-731904

The web app pre-fills the PIN and auto-retrieves the data.

---

Expiry and cleanup

• Default expiry: 744 hours (31 days) from creation
• Expired records are purged automatically after each new store operation
• Records are permanently destroyed after 3 failed PIN attempts
• The db_id field in responses identifies the database instance; it changes if the DB is wiped

Handling stale history

If the BiomAPI database is reset, existing PINs become invalid. Client apps should call GET /api/v1/status on startup and compare db_id to detect this:

const status = await fetch('/api/v1/status').then(r => r.json());
if (status.db_id !== storedDbId) {
  // Purge local history — all pins from the old instance are gone
}

The web app and History SDK handle this automatically.