Skip to main content
The Ciphera ecosystem relies on a Python FastAPI backend to handle on-chain transactions, verify Zero-Knowledge proofs, and manage the Shamir Secret Sharing threshold for court orders. This page documents the core API endpoints used by the SDK and the Custodian Dashboard.

​
Authentication

All endpoints that perform administrative or issuer-level actions (like creating court orders or executing revocations) require an API key passed in the headers. 
X-API-Key: ciphera-dev-secret-change-in-production

​
1. Widget Integration API

These endpoints are used automatically by the <Ciphera /> React widget during the user flow.

​
Get Issuer Public Key

<ResponseField name="GET" type="/api/v1/issuer/pubkey" /> Fetches the issuer’s uncompressed secp256k1 public key. The widget uses this to perform ECIES encryption on the user’s identity data before submission. The raw identity never reaches the backend. 
{
  "pubkey_hex": "04c2b9a7f...",
  "format": "secp256k1 uncompressed (04 || x || y)",
  "bytes": 65
}

​
Register KYC Proof

<ResponseField name="POST" type="/api/v1/register" /> The main KYC registration endpoint. It verifies the snarkjs Groth16 proof and, if mathematically valid, pays the Algorand transaction fee to register the nullifier on the NullifierRegistry smart contract. Body Parameters:
  • public_signals (array): The public inputs from the ZK proof (Nullifier, Merkle Root, App ID, etc).
  • proof (object): The mathematical pi_a, pi_b, pi_c proof objects.
  • encrypted_blob (string, optional): The ECIES-encrypted identity package.
{
  "success": true,
  "txid": "MC526N5AWJUZ57HEIUQATWVCLSW3GIYDDQGOKBYQCZSHRSZ4V7HQ",
  "nullifier_hex": "156f82bc6f8d385dfb...",
  "explorer_url": "https://allo.info/tx/MC52...",
  "demo": false
}

​
2. Custodian & Court Order API

These endpoints power the Custodian Dashboard and manage the conditional anonymity decryption flow.

​
Create Court Order [Issuer Auth Required]

<ResponseField name="POST" type="/api/v1/court-order" /> Initiates a court order against a specific nullifier. This alerts the 5 custodians that an identity reveal has been legally requested. Body Parameters:
  • nullifier_hex (string): The 64-character nullifier to target.
  • reason (string): The legal justification or case number.
  • pdf_url (string, optional): Link to the scanned court order.

​
Submit Custodian Vote

<ResponseField name="POST" type="/api/v1/court-order/{order_id}/vote" /> A custodian casts their vote. If this vote pushes the approvals to the 3 of 5 threshold, the backend instantly combines the HSM Shamir shares in-memory, decrypts the identity blob, and returns the identity in the response. Body Parameters:
  • custodian_id (string): The Algorand wallet address of the custodian.
  • custodian_num (int): Custodian index (1-5).
  • approved (boolean): true to approve, false to reject.
  • note (string, optional): Justification for the vote.
{
  "order_id": "8b9cad0e...",
  "status": "approved",
  "approvals": 3,
  "identity_decrypted": true,
  "message": "✅ Threshold reached! Identity decrypted in-memory.",
  "decrypted_identity": {
      "name": "Satish Kumar",
      "dob": "1995-01-01",
      "uid": "XXXX-XXXX-7432"
  },
  "identity_warning": "⚠️ Identity data is in-memory only. Displayed ONCE then discarded."
}

​
Execute On-Chain Revocation [Issuer Auth Required]

<ResponseField name="POST" type="/api/v1/court-order/{order_id}/execute" /> Executes the revocation for an approved court order. Calls the invalidate() method on the Algorand NullifierRegistry smart contract and deletes the Box storage, permanently banning the user from the KYC ecosystem.