API Documentation

Authentication

Protected routes require a Bearer token in the Authorization header. VeridexCore supports API key authentication and OIDC JWT authentication.

Authorization: Bearer <your_api_key>

API keys are provisioned by the system operator. There is no self-service key provisioning endpoint. Contact the operator to obtain an API key with a tenant and tier assignment.

The GET /health endpoint is unauthenticated. All other routes listed below require bearer authentication.

Core Routes

These are the currently implemented API routes.

Trust Path (authenticated)

Health (unauthenticated)

POST /attest

Submit an input/output pair. Returns a SHA-256 receipt, transparency log entry, Merkle root, and inclusion proof. Requires bearer authentication.

curl -X POST "https://veridexcore-api-vk223wugnq-uc.a.run.app/attest" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_api_key>" \
  -d '{
    "input": "What is the refund policy?",
    "output": "Refunds accepted within 30 days per §4.2",
    "metadata": {"system": "support-agent", "version": "2.1"}
  }'

metadata is optional. input and output are required.

Response

{
  "receipt": {
    "receipt_id": "a1b2c3...",
    "trace_id": "req_abc123",
    "input_hash": "...",
    "output_hash": "...",
    "timestamp": "2026-01-01T00:00:00+00:00",
    "mode": "TRANSITIONAL"
  },
  "attestation": null,
  "log_entry": {
    "index": 0,
    "entry_hash": "...",
    "prev_hash": "0000000000000000000000000000000000000000000000000000000000000000"
  },
  "merkle_root": "def456...",
  "inclusion_proof": {
    "leaf_index": 0,
    "leaf_count": 1,
    "path": []
  },
  "verify_url": "https://veridexcore.com/verify"
}

The attestation field is null unless VERIDEX_ENABLE_EXPORT_ATTESTATION=true is configured on the server. When populated, it contains the Merkle root, inclusion proof path, and verification status needed for /verify-package.

POST /verify-package

Verify a previously attested receipt package against the canonical transparency log. Requires bearer authentication. The receipt must exist in the authenticated tenant's log.

curl -X POST "https://veridexcore-api-vk223wugnq-uc.a.run.app/verify-package" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_api_key>" \
  -d '{
    "format_version": "1.0",
    "package": {
      "receipt": { "receipt_id": "a1b2c3...", "trace_id": "...", "input_hash": "...", "output_hash": "...", "timestamp": "...", "mode": "TRANSITIONAL" },
      "attestation": { "receipt_digest": "a1b2c3...", "log_index": 0, "log_size": 1, "merkle_root": "...", "inclusion_proof_path": [], "verified": true, "failure_reason": null }
    }
  }'

Response

{
  "is_valid": true,
  "receipt_digest": "a1b2c3...",
  "log_index": 0,
  "log_size": 1,
  "merkle_root": "def456...",
  "failure_reason": null
}

If verification fails, is_valid is false and failure_reason is one of:

• RECEIPT_NOT_IN_LOG — receipt hash not found in the tenant's transparency log
• PROOF_INVALID — Merkle inclusion proof fails verification
• ROOT_HISTORY_MISMATCH — root does not match recorded root history
• ANCHOR_MISMATCH — root does not match anchor journal

Transparency Log

Query your tenant's transparency log state. Both routes require bearer authentication.

curl "https://veridexcore-api-vk223wugnq-uc.a.run.app/log/root" -H "Authorization: Bearer <your_api_key>"

# Response:
# {"root": "abc123...", "log_size": 42, "timestamp": "2026-01-01T00:00:00+00:00"}

GET /audit/export

Export your tenant's audit trail as NDJSON. Requires bearer authentication. Optional query parameters: start, end (ISO8601 timestamps),event_type (exact match filter).

curl "https://veridexcore-api-vk223wugnq-uc.a.run.app/audit/export?start=2026-01-01T00:00:00Z&end=2026-01-31T23:59:59Z" \
  -H "Authorization: Bearer <your_api_key>"

Response content type is application/x-ndjson. Each line is a JSON object with idx, timestamp, event_type, route,outcome, prev_hash, and event_hash. Audit integrity is verified before export.

GET /health

Unauthenticated. Returns service status and component checks.

curl "https://veridexcore-api-vk223wugnq-uc.a.run.app/health"

# Response:
# {"status": "ok", "service": "veridexcore", "version": "1.0.0", "checks": {"secret_key_set": true, "db_initialized": true}}

Errors

The API uses standard HTTP status codes. Error responses return JSON with a detail field.

Notes & Limitations

• API keys are provisioned by the operator. No self-service registration endpoint exists.
• All protected routes accept API key or OIDC JWT bearer tokens. OIDC requires server-side IdP configuration.
• The attestation field in /attest responses requires VERIDEX_ENABLE_EXPORT_ATTESTATION=true on the server.
• Each API key is bound to a tenant. All data (transparency log, audit trail) is tenant-isolated.
• The /audit/export endpoint verifies audit chain integrity before returning data.
• Replay detection rejects duplicate receipt hashes within the same tenant with HTTP 409.