Quickstart

Tu primer request autenticado al Public API en menos de 10 minutos.

← Volver a la API Reference

1.Pedí tu API key

Mandá un email a equipo@geoevidence.com con:

  • Nombre de tu organización
  • Email técnico del responsable
  • Casos de uso previstos (3-5 bullets)
  • Tier de acceso requerido: test (sandbox) o live (producción)

Te respondemos en 1-2 días hábiles con tu API_KEY y HMAC_SECRET por canal seguro (1Password share).

⚠️ El HMAC_SECRET se muestra UNA sola vez al admin que emite la key. Guardalo en tu password manager / secrets manager antes de cerrar esa ventana.

2.Armá tu primera request

Cada request al Public API requiere dos elementos en los headers:

  • Authorization: Bearer <API_KEY>
  • X-GeoEvidence-Signature: t=<ts>,v1=<sig> donde sig es un HMAC-SHA256 que vas a calcular en cada request.

3.Calculá la firma HMAC

El payload firmado es exactamente <ts>.<method>.<path>.<sha256(body_bytes_hex)> (todo como string, separado por puntos). Ejemplo en Python:

python
import hashlib, hmac, time
import httpx

api_key = "geoev_live_xxxxxxxx"            # la que te pasamos
hmac_secret = bytes.fromhex("...")         # el HMAC_SECRET que te pasamos
evidence_id = "3c63f199f94ce0f7566d3789057b6b6e"
path = f"/api/v1/evidence/{evidence_id}"

ts = int(time.time())
body_hash = hashlib.sha256(b"").hexdigest()
signed = f"{ts}.GET.{path}.{body_hash}".encode()
sig = hmac.new(hmac_secret, signed, hashlib.sha256).hexdigest()

resp = httpx.get(
    f"https://api.geoevidence.com{path}",
    headers={
        "Authorization": f"Bearer {api_key}",
        "X-GeoEvidence-Signature": f"t={ts},v1={sig}",
    },
)
resp.raise_for_status()
evidence = resp.json()
print(evidence["server_hash"])

El mismo patrón en cURL:

bash
TS=$(date +%s)
BODY_HASH=$(echo -n "" | sha256sum | awk '{print $1}')
PATH_PART="/api/v1/evidence/3c63f199f94ce0f7566d3789057b6b6e"
PAYLOAD="${TS}.GET.${PATH_PART}.${BODY_HASH}"
SIG=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$HMAC_SECRET" | awk '{print $2}')

curl -X GET "https://api.geoevidence.com${PATH_PART}" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-GeoEvidence-Signature: t=${TS},v1=${SIG}"

4.Manejá la respuesta y los errores

Respuestas exitosas (200) traen el Evidence object con todos los campos. Errores (4xx, 5xx) traen este shape:

json
{
  "code": "AUTH_INVALID",
  "message": "API key no encontrada",
  "request_id": "8c2f7a4e-9d1b-4e3f-7a8c-2d6e9f1b4a7c"
}

Siempre incluí el request_id cuando reportes un problema a soporte. Aparece también en el response header X-Request-Id para correlación con nuestros logs.

Catálogo completo de errores:

  • AUTH_MISSING (401), AUTH_FORMAT (401), AUTH_INVALID (401), AUTH_REVOKED (401)
  • HMAC_MISSING (401), HMAC_INVALID (401), HMAC_EXPIRED (401), HMAC_REPLAY (409)
  • RATE_LIMIT_EXCEEDED (429) — respetar Retry-After
  • INTERNAL_ERROR (500) — reportar request_id

5.Probá el flujo end-to-end

Cuando tu código esté listo:

  1. Hacé un GET /api/v1/evidence/<id> con una evidencia que ya tengas en tu base (o usá una de las públicas de la landing).
  2. Validá que integrity_match y signature_valid sean true.
  3. Si está anclada (anchor_id presente), hacé GET /api/v1/zk-proof/<anchor_id> y verificá que el merkle_root coincida con el calculado localmente.
  4. Hacé GET /api/v1/kaspa/verify/<kaspa_tx_id> y verificá que is_accepted sea true.

Si los 3 checks pasan, tu integración está completa. Reportanos a equipo@geoevidence.com y te agendamos una llamada de feedback.

6.Próximos pasos

  • API Reference completa — los 6 endpoints read-only con code samples en cURL, Python y TypeScript.
  • CHANGELOG — breaking changes y deprecation timeline (6 meses de aviso).
  • Auth spec v1 — detalle completo del modelo de auth, scopes, rotación y revocación.
  • SLA — tiempos de respuesta, soporte, rate limits, qué se compromete en POC-ready vs ship-ready.
  • Readiness table v1 — qué承诺 el Public API (POC-ready, ship-ready).
  • ADR-0006 (arquitectura) — por qué hybrid y no gateway separado.