API

API pública

El production API origin para SDKs y verificación pública es https://verify.attesto.eu. Los tenant browser workflows viven en https://dashboard.attesto.eu.

Elija la familia API correcta

Attesto tiene varias surfaces públicas porque el trabajo de evidence ocurre en lugares diferentes. Use el SDK/API desde su servidor para crear evidence, webhooks para recibir lifecycle notifications, connectors para capturar source-system observations y verifier endpoints cuando otro sistema necesite revisar evidence antes de confiar en ella.

Origins

Authentication

Server-side event ingest usa una tenant system key en el header Authorization: Bearer. Public verification routes validan los proof objects enviados y no requieren tenant cookies. Las tenant dashboard routes usan la secure browser session existente más CSRF recovery para mutating requests. No coloque system keys ni SSO client secrets en frontend bundles.

curl -X POST https://verify.attesto.eu/v1/sdk/events \
  -H "Authorization: Bearer $ATTESTO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $ATTESTO_IDEMPOTENCY_KEY" \
  --data-binary @event.json

Email-first authentication routes

Los main tenant users inician sesión mediante email discovery en dashboard.attesto.eu. Attesto devuelve un único next step recomendado en lugar de mostrar todos los providers a la vez. Las marketplace developer accounts, admin staff auth y auditor auth siguen siendo superficies separadas.

Consulte Tenant SSO para la guía de setup de Entra ID, generic OIDC y SAML.

Source time y timezone policy

Attesto registra cuándo el source system dice que ocurrió un event y cuándo Attesto lo recibió. Las Event APIs requieren timezone-aware timestamps como 2026-06-07T12:00:00+02:00 o 2026-06-07T10:00:00Z. Tenant timezone es configurable; los systems heredan por defecto la tenant timezone y pueden establecer su propio source_timezone cuando la fuente conectada opera en otra jurisdicción.

Idempotency y replay behavior

Las write routes aceptan Idempotency-Key. Repetir la misma key con la misma canonical request devuelve el resultado original. Repetir la misma key con una request diferente falla como conflicto. Esto protege connector retries y server-side job retries de crear evidence duplicada.

v1 event ingest

Use v1 cuando necesite el stable event audit trail y anchoring path. Los SDKs configuran defaults para event type, status, retries e idempotency.

• POST /v1/sdk/events registra un event.
• POST /v1/sdk/events/batch registra hasta 1000 events.
• GET /v1/events/{eventId}/proof devuelve anchored proof material para un event.
• POST /v1/public/verify verifica un v1 proof object.
• POST /v1/exports/{exportId}/truth-package/verify registra un event backend-validated truth_package.verified después de que un verifier report prueba que el package exportado fue revisado criptográficamente.

Tenant dashboard v1 APIs

Estas browser APIs impulsan dashboard.attesto.eu. Las llamadas mutating usan tenant session cookies y CSRF recovery. Usa system keys y SDK routes para server-side ingest; usa estas routes para tenant operators que gestionan su workspace.

Event body mínimo:

{
  "type": "ai.decision",
  "status": "verified",
  "occurred_at": "2026-06-07T12:00:00Z",
  "source_ref": "case-2026-0001",
  "payload": {
    "model": "risk-classifier-v4",
    "decision": "manual_review",
    "policy_id": "policy-2026-01"
  }
}

v2 Proofstream

Proofstream añade append-only streams, signed receipts, windows, checkpoints, witness evidence, anchors, bundles y offline verification.

• POST /v2/streams crea un stream.
• POST /v2/streams/{streamId}/events añade un event y devuelve un signed receipt.
• POST /v2/streams/{streamId}/events/batch añade varios events con receipt results.
• GET /v2/streams/{streamId}/head devuelve el stream head append-only actual.
• GET /v2/receipts/{eventId} devuelve el receipt almacenado.
• POST /v2/verify/receipt verifica directamente un receipt object.
• GET /v2/windows/{windowId} devuelve window evidence e inclusion material.
• GET /v2/checkpoints/{checkpointId} devuelve checkpoint evidence.
• GET /v2/checkpoints/{checkpointId}/consistency?from=... devuelve consistency evidence.
• GET /v2/witness/policies/{policyId} devuelve la witness policy usada para quorum checks.
• GET /v2/anchors/{anchorEpochId} devuelve anchor epoch evidence.
• GET /v2/ivc/epochs/{ivcEpochId} devuelve Proof of Evolution epoch evidence.
• POST /v2/audit/packs crea un offline verifier bundle cuando la range tiene la witness y anchor evidence requerida.
• POST /v2/verify verifica receipt, stream, checkpoint, consistency, anchor, IVC o bundle objects.

Crear un stream:

curl -X POST https://verify.attesto.eu/v2/streams \
  -H "Authorization: Bearer $ATTESTO_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<JSON
{
  "system_id": "sys_...",
  "use_case": "ai-decision-history",
  "policy_id": "policy-2026-01",
  "metadata": {
    "owner": "risk-platform",
    "environment": "production"
  }
}
JSON

Añadir un event:

curl -X POST https://verify.attesto.eu/v2/streams/$STREAM_ID/events \
  -H "Authorization: Bearer $ATTESTO_API_KEY" \
  -H "Idempotency-Key: $ATTESTO_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<JSON
{
  "source_ref": "case-2026-0001:decision-1",
  "event_type": "ai.decision",
  "occurred_at": "2026-06-07T12:00:00+02:00",
  "payload": {
    "decision": "manual_review",
    "score": 91,
    "policy_id": "policy-2026-01"
  }
}
JSON

Receipt response shape:

{
  "stream_event_id": "sev_...",
  "stream_id": "str_...",
  "seq_no": 1,
  "event_hash": "sha256-hex",
  "stream_head_hash": "sha256-hex",
  "receipt": {
    "protocol": "ATTESTO-PROOFSTREAM-001",
    "alg": "Ed25519",
    "kid": "proofstream-receipt-key",
    "signature": "hex-encoded-signature"
  }
}

Tenant Proofstream y dashboard APIs

Las Tenant browser APIs exponen el mismo evidence model dentro del dashboard sin dar al frontend acceso a server-side system keys. Las mutating dashboard calls usan browser cookies y CSRF recovery.

Tenant settings y SSO APIs

Tenant settings solo está disponible para authenticated tenant users con el rol requerido. Los provider secrets se cifran server-side y nunca se devuelven al browser después de guardar.

Connector y Local Vault APIs

Connectors son production evidence sources. Los tenant users configuran connector records en el dashboard, mientras los source systems publican events mediante provider-specific signed envelopes o Local Vault relay. Cada connector event debe incluir source system, source object, source event type, source timestamp con timezone, idempotency reference y normalized payload commitment.

Marketplace APIs

Las Marketplace APIs impulsan marketplace.attesto.eu. El public catalog es read-only. Tenant acquisition, installation, artifact download y revocation requieren una authenticated tenant session más CSRF. Publisher signup, profile management, developer checkout, payout onboarding y asset submission usan una cuenta separada marketplace-only developer. La documentación pública omite intencionalmente los endpoints privados de Attesto review y publication.

Public status API

status.attesto.eu expone health customer-safe para servicios públicos. Incluye component status, latency, uptime bars, incident summaries, generated time y timezone metadata. No expone private admin status, tenant identifiers, logs, secrets, provider payloads ni raw database details.

• GET https://status.attesto.eu/health devuelve status-service health.
• GET https://status.attesto.eu/api/status devuelve el public status payload usado por la página.
• GET https://status.attesto.eu/v1/status es el versioned status payload alias.

Consulte Public status page para el public visibility model y la component list.

Comportamiento de verificación

Verification falla cerrado ante malformed objects, changed payloads, changed sequence numbers, removed o inserted events, stale checkpoints, wrong witness signatures, wrong anchors y ambiguous fork evidence.

Truth Package downloads y verification son lifecycle events separados. Una descarga registra truth_package.accessed, probando que el package fue servido. Un verifier report exitoso enviado a /v1/exports/{exportId}/truth-package/verify registra truth_package.verified, probando que un verifier revisó el package hash, manifest hash y artifacts incluidos. El ZIP hash final se registra después de finalizar los ZIP bytes y no se inserta de vuelta en el mismo ZIP; eso evita circular self-reference mientras mantiene los bytes descargables independientemente hasheables.

curl -X POST https://dashboard.attesto.eu/v1/exports/$EXPORT_ID/truth-package/verify \
  -H "Authorization: Bearer $ATTESTO_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @truth-package-verification-report.json

curl -X POST https://verify.attesto.eu/v2/verify \
  -H "Content-Type: application/json" \
  --data-binary @attesto-bundle.json

Error semantics