Verification API reference

Base URL

https://api.jagaan.com/api/v1

Health check

GET/health/

Service status and current platform counters.

curl https://api.jagaan.com/api/v1/health/

{
  "ok": true,
  "service": "jagaan-verification-api",
  "version": "1.0",
  "timestamp": "2026-06-23T15:30:00Z",
  "stats": {
    "registered_checks": 12,
    "total_requests": 1234
  }
}

Get a verification

GET/verification/<uid>/

The full record: badge, score, checks, signature material and embed URLs.

curl https://api.jagaan.com/api/v1/verification/V-XXXX/

{
  "ok": true,
  "uid": "V-XXXX",
  "status": "verified",
  "badge": {
    "slug": "premium",
    "name": "Premium Verified",
    "icon": "fa-solid fa-shield-check"
  },
  "score": { "total": "9.60", "max": "9.60", "percent": 100.0 },
  "timeline": {
    "completed_at": "2026-06-23T15:30:00Z",
    "expires_at": "2027-06-23T15:30:00Z",
    "days_until_expiry": 335
  },
  "checks": [
    {
      "type": "owner_identity",
      "label": "Owner Identity",
      "status": "auto_verified",
      "weight": 1.5,
      "final_score": 100.0,
      "evidence_count": 2
    }
  ],
  "signature": {
    "algorithm": "RSA-2048 + HMAC-SHA256",
    "rsa_valid": true,
    "hmac_valid": true,
    "sha256_matches": true,
    "signature_valid": true,
    "public_key_pem": "-----BEGIN PUBLIC KEY-----..."
  },
  "public_url": "https://jagaan.com/verification/public/V-XXXX/"
}

Response fields

Rate limits

• 100 requests a minute per IP on the verification endpoint.
• 10 requests a minute per IP on the health endpoint.
• Exceeding a limit returns 429 with a retry_after field.
• Responses carry Cache-Control: max-age=30 for edge caching.

Webhooks

Push verification events to your own server. Every delivery is HMAC signed and retried up to five times. Configure endpoints under Verifications in your dashboard.

POST https://your-server.com/webhook

X-Jagaan-Event: verification.completed
X-Jagaan-Event-ID: evt_abc123
X-Jagaan-Signature: t=1700000000,v1=<hmac-sha256>
X-Jagaan-Delivery-ID: 12345
X-Jagaan-Attempt: 1

{
  "event": "verification.completed",
  "verification": {
    "uid": "V-XXXX",
    "status": "verified",
    "score_total": "9.60",
    "badge_slug": "premium"
  },
  "timestamp": 1700000000,
  "event_id": "evt_abc123"
}

Verify the signature before trusting a payload:

import hmac, hashlib

secret = "your-webhook-secret"
timestamp = "1700000000"
payload = request.body.decode()

expected = hmac.new(
    secret.encode(),
    f"{timestamp}.{payload}".encode(),
    hashlib.sha256,
).hexdigest()

assert hmac.compare_digest(expected, signature_from_header)

Other endpoints