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, and patient name/initials plus patient ID are redacted from the stored BiomPIN payload.

---

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.

Patient name/initials and patient ID are also removed before the encrypted payload is stored. The initial /process response still contains identifiers, but retrieving a BiomPIN from another browser or device returns empty identifiers.

Browser-local identity context

The web app can restore identifiers locally when they are already known to that browser. It uses exact-PIN local history, and integrations may pass a browser-only fragment:

https://biomapi.com/pin/lunar-rocket-731904#biomctx=<base64url-json>

biomctx is not sent to the server. Version 1 contains only:

{
  "v": 1,
  "patient_name": "JD",
  "patient_id": "12345"
}

Use a URL fragment, not query parameters, for patient identifiers.

JavaScript Integration SDK

BiomAPI serves a lightweight, dependency-free browser integration SDK at biompin-sdk.js to automate client-side sharing history and private patient context handoff in external calculators.

• SDK Raw File: biompin-sdk.js
• Detailed Integration Guide: Refer to the comprehensive BiomPIN JavaScript SDK Integration Guide for the full API documentation, localStorage schemas, and encryption hash serialization specifications.

---

Generating a BiomPIN

BiomPIN is opt-in for the API: pass biompin=true on POST /api/v1/biom/process.

curl -X POST .../process \
  -F "file=@report.pdf" \
  -F "biompin=true"

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 BiomPIN database instance