API

Public API

La production API origin per SDKs e public verification è https://verify.attesto.eu. I tenant browser workflows vivono su https://dashboard.attesto.eu.

Scegliere la API family corretta

Attesto ha più public surfaces perché l'evidence work avviene in luoghi diversi. Usa SDK/API dal tuo server per creare evidence, webhooks per ricevere lifecycle notifications, connectors per catturare source-system observations e verifier endpoints quando un altro sistema deve controllare evidence prima di fidarsi.

Origins

Authentication

Server-side event ingest usa una tenant system key nell'header Authorization: Bearer. Public verification routes valida i proof objects forniti e non richiede tenant cookies. Le tenant dashboard routes usano la secure browser session esistente più CSRF recovery per mutating requests. Non inserire system keys o SSO client secrets nei 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

I main tenant users accedono tramite email discovery su dashboard.attesto.eu. Attesto restituisce un solo next step raccomandato invece di mostrare tutti i providers insieme. Marketplace developer accounts, admin staff auth e auditor auth restano surfaces separate.

Vedi Tenant SSO per la guida setup di Entra ID, generic OIDC e SAML.

Source time e timezone policy

Attesto registra quando il source system dichiara che un event è avvenuto e quando Attesto lo ha ricevuto. Le Event APIs richiedono timezone-aware timestamps come 2026-06-07T12:00:00+02:00 o 2026-06-07T10:00:00Z. Tenant timezone è configurabile; systems eredita di default la tenant timezone e può impostare il proprio source_timezone quando la fonte collegata opera in un'altra giurisdizione.

Idempotency e replay behavior

Write routes accetta Idempotency-Key. Ripetere la stessa key con la stessa canonical request restituisce il result originale. Ripetere la stessa key con una request diversa fallisce come conflict. Questo protegge connector retries e server-side job retries dalla creazione di evidence duplicata.

v1 event ingest

Usa v1 quando ti serve lo stable event audit trail e anchoring path. Gli SDKs impostano defaults per event type, status, retries e idempotency.

• POST /v1/sdk/events logga un event.
• POST /v1/sdk/events/batch logga fino a 1000 events.
• GET /v1/events/{eventId}/proof restituisce anchored proof material per 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 dopo che un verifier report prova che il package esportato è stato controllato crittograficamente.

Tenant dashboard v1 APIs

Queste browser APIs alimentano dashboard.attesto.eu. Le mutating calls usano tenant session cookies e CSRF recovery. Usa system keys e SDK routes per server-side ingest; usa queste routes per tenant operators che gestiscono il workspace.

Minimal event body:

{
  "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 aggiunge append-only streams, signed receipts, windows, checkpoints, witness evidence, anchors, bundles e offline verification.

• POST /v2/streams crea uno stream.
• POST /v2/streams/{streamId}/events aggiunge un event e restituisce un signed receipt.
• POST /v2/streams/{streamId}/events/batch aggiunge più events con receipt results.
• GET /v2/streams/{streamId}/head restituisce lo stream head append-only corrente.
• GET /v2/receipts/{eventId} restituisce il receipt archiviato.
• POST /v2/verify/receipt verifica direttamente un receipt object.
• GET /v2/windows/{windowId} restituisce window evidence e inclusion material.
• GET /v2/checkpoints/{checkpointId} restituisce checkpoint evidence.
• GET /v2/checkpoints/{checkpointId}/consistency?from=... restituisce consistency evidence.
• GET /v2/witness/policies/{policyId} restituisce la witness policy usata per quorum checks.
• GET /v2/anchors/{anchorEpochId} restituisce anchor epoch evidence.
• GET /v2/ivc/epochs/{ivcEpochId} restituisce Proof of Evolution epoch evidence.
• POST /v2/audit/packs crea un offline verifier bundle quando la range ha la witness e anchor evidence richiesta.
• POST /v2/verify verifica receipt, stream, checkpoint, consistency, anchor, IVC o bundle objects.

Crea uno 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

Aggiungi 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 e dashboard APIs

Le Tenant browser APIs espongono lo stesso evidence model nel dashboard senza dare al frontend accesso ai server-side system keys. Le mutating dashboard calls usano browser cookies e CSRF recovery.

Tenant settings e SSO APIs

Tenant settings è disponibile solo per authenticated tenant users con il ruolo richiesto. I provider secrets sono cifrati server-side e non vengono mai restituiti al browser dopo il salvataggio.

Connector e Local Vault APIs

Connectors sono production evidence sources. Tenant users configurano connector records nel dashboard, mentre source systems inviano events tramite provider-specific signed envelopes o Local Vault relay. Ogni connector event deve includere source system, source object, source event type, source timestamp con timezone, idempotency reference e normalized payload commitment.

Marketplace APIs

Le Marketplace APIs alimentano marketplace.attesto.eu. Il public catalog è read-only. Tenant acquisition, installation, artifact download e revocation richiedono una authenticated tenant session più CSRF. Publisher signup, profile management, developer checkout, payout onboarding e asset submission usano un account separato marketplace-only developer. La documentazione pubblica omette intenzionalmente gli endpoint privati di Attesto review e publication.

Public status API

status.attesto.eu espone health customer-safe per i servizi pubblici. Include component status, latency, uptime bars, incident summaries, generated time e timezone metadata. Non espone private admin status, tenant identifiers, logs, secrets, provider payloads o raw database details.

• GET https://status.attesto.eu/health restituisce status-service health.
• GET https://status.attesto.eu/api/status restituisce il public status payload usato dalla pagina.
• GET https://status.attesto.eu/v1/status è il versioned status payload alias.

Vedi Public status page per il public visibility model e la component list.

Verification behavior

Verification fail-closed su malformed objects, changed payloads, changed sequence numbers, removed o inserted events, stale checkpoints, wrong witness signatures, wrong anchors e ambiguous fork evidence.

Truth Package downloads e verification sono lifecycle events separati. Un download registra truth_package.accessed, provando che il package è stato servito. Un verifier report riuscito inviato a /v1/exports/{exportId}/truth-package/verify registra truth_package.verified, provando che un verifier ha controllato package hash, manifest hash e included artifacts. Il final ZIP hash viene registrato dopo la finalizzazione dei ZIP bytes e non viene reinserito nello stesso ZIP; questo evita circular self-reference mantenendo i bytes scaricabili indipendentemente hashabili.

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