Sanad Verify API

A signed, public, read-only endpoint that lets any consumer ask: "is this entity compliant with India's DPDP Act 2023 and CERT-In Directives, right now?" -- and get back a cryptographically verifiable JSON proof.

Built for cyber-insurance underwriters, lenders, procurement teams, auditors, and regulators who need machine-verifiable compliance evidence without trusting any single party's word.

Quick start

POST a tenant_id (or license_key). Get back a signed JSON. Verify the signature offline against our published public key.

curl -X POST https://www.cognoshift.in/api/verify/v1/check \
  -H 'Content-Type: application/json' \
  -d '{
    "tenant_id":   "22e19c95-eae9-41c6-bbb3-c57e21ff5d06",
    "consumer_id": "icici-cyber-cover-underwriter"
  }'

L1 (current): no API key required. Rate-limited per IP. L2: issue consumer API keys for metered billing. L3: govt revenue-share + circular hooks.

Response shape

Every response is a signed envelope. payload is the canonicalised JSON (RFC 8785-style key sorting); signature is ed25519 over the SHA-256 of the canonical payload.

{
  "payload": {
    "receipt_id":      "VR-3a7af4b2e8",
    "entity_ref":      "22e19c95-...",
    "entity_name":     "Acme Public School",
    "compliance_state":"PARTIAL",
    "score":           73,
    "directives": {
      "automated":     5,
      "self_attested": 12,
      "failing":       3,
      "not_configured":0,
      "total":         20
    },
    "sentinel": {
      "active":           true,
      "endpoints_online": 14,
      "last_heartbeat":   "2026-05-12T11:09Z"
    },
    "last_dpia_approved_at": "2026-04-18T00:00:00Z",
    "last_breach_filed_at":  null,
    "sentinel_attestation": {
      "provider":     "Microsoft Platform Crypto Provider",
      "tpm_anchored": true
    },
    "evaluated_at":      "2026-05-12T11:42:00Z",
    "verify_chain_url":  "https://www.cognoshift.in/api/verify/v1/chain/VR-3a7af4b2e8",
    "service_version":   "verify-v1",
    "attribution":       "Sanad Verify (CognoShift)"
  },
  "payload_hash": "e8f6a3...",
  "signature":    "<ed25519-base64>",
  "public_key":   "<spki-der-base64>",
  "algorithm":    "ed25519",
  "signed_at":    "2026-05-12T11:42:00Z"
}

Verifying a response offline

1. Fetch the current Verify API public key from /api/verify/v1/public-key. Cache it for 24 h.
2. Take the payload object from the signed envelope. Canonicalise: sort object keys recursively (RFC 8785-style).
3. Compute SHA-256 of the canonicalised string. This is the payload_hash.
4. Verify signature (base64 ed25519) against the hash, using the public key from step 1.
5. If valid: the response was issued by Sanad's Verify service at signed_at and the entity's state was as described. We cannot retroactively alter what we said.

Reference implementations of step 2-4 in three languages are available in the Sanad Verifier SDK at /docs/verifier-sdk.

Receipts

Every response carries a receipt_id (e.g. VR-3a7af4b2e8). The same response can be re-fetched verbatim at:

curl https://www.cognoshift.in/api/verify/v1/chain/<RECEIPT_ID>

Use this when you need to hand a third party a single URL that resolves to a signed JSON they can verify. The receipt is cached for the lifetime of the Sanad Verify service.

Public key

curl https://www.cognoshift.in/api/verify/v1/public-key

JWKS-style envelope. Single ed25519 key today, with planned rotation policy in v2. x_spki_b64 is the SPKI-DER public key in base64.

What "compliant" means here

compliance_state is computed from two signals:

The directives object splits Sentinel-evidenced ("automated") from self-attested counts, so a consumer can apply their own threshold. The sentinel_attestation object surfaces whether the agent uses TPM 2.0 hardware signing (provider == Microsoft Platform Crypto Provider).

Opt-in semantics

Entities are not queryable by default. An entity owner enables verification in the Sanad portal (settings -- coming in L2 UI; SQL-only today). Until then, the Verify API returns ENTITY_NOT_PUBLIC (403). This prevents the Verify endpoint from being used as an enumeration oracle.

Roadmap

• L1 live Public read-only check, signed responses, receipts, public key endpoint.
• L2 next Consumer API keys, per-call metering, usage dashboard, paid plans.
• L3 next Govt revenue-share, circular-trigger webhooks, DPB Board telemetry feed.