API Reference

Endpoints Overview

ZK-eSIM provides a set of REST API endpoints to interact with the backend verification server. These endpoints allow you to verify identity proofs, purchase eSIM plans, and activate eSIMs, all while preserving user privacy via zero-knowledge proofs.

Endpoint	Method	Description
/auth/proof	POST	Verify ZK identity proof
/buy-esim	POST	Issue ZK tariff credential
/activate	POST	Activate eSIM

---

1. /auth/proof - Verify ZK Identity Proof

Description:

Verify that the user’s pseudonymous eSIM identity is valid using a zero-knowledge proof. No sensitive data such as IMSI or real user information is sent.

Request Example (JSON):

{
  "proof": "<zk-proof-json>",
  "pseudo_id": "user123"
}

Response Example (JSON):

{
  "status": "ok",
  "message": "ZK proof verified. eSIM identity confirmed."
}

Notes:

• proof → JSON object generated by client-side prover

• pseudo_id → pseudonymous identifier for the eSIM

---

2. /buy-esim - Issue ZK Tariff Credential

Description:

Used to purchase or issue a tariff/plan while maintaining user anonymity. The server verifies the zero-knowledge proof of payment or subscription validity.

Request Example (JSON):

{
  "proof": "<zk-payment-proof>",
  "pseudo_id": "user123",
  "planId": "data-plan-1"
}

Response Example (JSON):

{
  "status": "ok",
  "message": "eSIM plan issued successfully."
}

Notes:

• planId → identifier of the chosen tariff or plan

• The proof confirms that the user has paid or is eligible, without revealing identity

---

3. /activate - Activate eSIM

Description:

Activate the eSIM using a zero-knowledge proof generated from either identity verification or plan purchase. The server verifies the proof and updates the eSIM status.

Request Example (JSON):

{
  "proof": "<zk-activation-proof>",
  "pseudo_id": "user123"
}

Response Example (JSON):

{
  "status": "ok",
  "message": "eSIM activated successfully."
}

Notes:

• This endpoint is the final step in the eSIM workflow

• Ensures that activation is fully private and cryptographically verified

---

Usage Tips

• Always generate ZK proofs on the client side; never send raw IMSI or personal data.

• Verify the proof immediately after generation to confirm validity before sending.

• Combine /buy-esim and /activate in one flow for testing the MVP.

• Use pseudo_id consistently across calls to simulate the same eSIM identity.

---

GitBook Syntax Highlighting Recommendation

Content Type	Syntax Highlighting
JSON requests/responses	json
Terminal commands (curl)	bash
TypeScript/JS client examples	ts