API

Public API

De production API origin voor SDKs en publieke verificatie is https://verify.attesto.eu. Tenant browser workflows staan op https://dashboard.attesto.eu.

Kies de juiste API family

Attesto heeft meerdere publieke surfaces omdat evidence work op verschillende plekken gebeurt. Gebruik de SDK/API vanaf je server om evidence te maken, webhooks om lifecycle notifications te ontvangen, connectors om source-system observations vast te leggen en verifier endpoints wanneer een ander systeem evidence moet controleren voordat het daarop vertrouwt.

Origins

Authentication

Server-side event ingest gebruikt een tenant system key in de Authorization: Bearer header. Public verification routes valideren aangeleverde proof objects en vereisen geen tenant cookies. Tenant dashboard routes gebruiken de bestaande secure browser session plus CSRF recovery voor mutating requests. Plaats geen system keys of SSO client secrets in 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

Main tenant users loggen in via email discovery op dashboard.attesto.eu. Attesto retourneert één aanbevolen next step in plaats van alle providers tegelijk te tonen. Marketplace developer accounts, admin staff auth en auditor auth blijven aparte surfaces.

Zie Tenant SSO voor de Entra ID, generic OIDC en SAML setup guide.

Source time en timezone policy

Attesto registreert wanneer het source system zegt dat een event plaatsvond en wanneer Attesto het ontving. Event APIs vereisen timezone-aware timestamps zoals 2026-06-07T12:00:00+02:00 of 2026-06-07T10:00:00Z. Tenant timezone is configureerbaar; systems erven standaard de tenant timezone en kunnen hun eigen source_timezone zetten wanneer de verbonden bron in een andere jurisdiction draait.

Idempotency en replay behavior

Write routes accepteren Idempotency-Key. Dezelfde key met hetzelfde canonical request herhalen retourneert het oorspronkelijke result. Dezelfde key met een ander request herhalen faalt als conflict. Dit beschermt connector retries en server-side job retries tegen dubbele evidence.

v1 event ingest

Gebruik v1 wanneer je de stable event audit trail en anchoring path nodig hebt. SDKs zetten defaults voor event type, status, retries en idempotency.

• POST /v1/sdk/events logt één event.
• POST /v1/sdk/events/batch logt tot 1000 events.
• GET /v1/events/{eventId}/proof retourneert anchored proof material voor een event.
• POST /v1/public/verify verifieert een v1 proof object.
• POST /v1/exports/{exportId}/truth-package/verify legt een backend-validated truth_package.verified event vast nadat een verifier report bewijst dat het geëxporteerde package cryptografisch is gecontroleerd.

Tenant dashboard v1 APIs

Deze browser APIs voeden dashboard.attesto.eu. Muterende calls gebruiken tenant session cookies en CSRF recovery. Gebruik system keys en SDK routes voor server-side ingest; gebruik deze routes voor tenant operators die hun workspace beheren.

Minimale 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 voegt append-only streams, signed receipts, windows, checkpoints, witness evidence, anchors, bundles en offline verification toe.

• POST /v2/streams maakt een stream.
• POST /v2/streams/{streamId}/events voegt één event toe en retourneert een signed receipt.
• POST /v2/streams/{streamId}/events/batch voegt meerdere events toe met receipt results.
• GET /v2/streams/{streamId}/head retourneert de huidige append-only stream head.
• GET /v2/receipts/{eventId} retourneert de opgeslagen receipt.
• POST /v2/verify/receipt verifieert één receipt object direct.
• GET /v2/windows/{windowId} retourneert window evidence en inclusion material.
• GET /v2/checkpoints/{checkpointId} retourneert checkpoint evidence.
• GET /v2/checkpoints/{checkpointId}/consistency?from=... retourneert consistency evidence.
• GET /v2/witness/policies/{policyId} retourneert de witness policy voor quorum checks.
• GET /v2/anchors/{anchorEpochId} retourneert anchor epoch evidence.
• GET /v2/ivc/epochs/{ivcEpochId} retourneert Proof of Evolution epoch evidence.
• POST /v2/audit/packs maakt een offline verifier bundle wanneer de range de vereiste witness en anchor evidence heeft.
• POST /v2/verify verifieert receipt, stream, checkpoint, consistency, anchor, IVC of bundle objects.

Maak een 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

Voeg een event toe:

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 en dashboard APIs

Tenant browser APIs tonen hetzelfde evidence model in het dashboard zonder frontend toegang tot server-side system keys. Mutating dashboard calls gebruiken browser cookies en CSRF recovery.

Tenant settings en SSO APIs

Tenant settings zijn alleen beschikbaar voor authenticated tenant users met de vereiste rol. Provider secrets worden server-side versleuteld en worden na opslaan nooit teruggegeven aan de browser.

Connector en Local Vault APIs

Connectors zijn production evidence sources. Tenant users configureren connector records in het dashboard, terwijl source systems events posten via provider-specific signed envelopes of Local Vault relay. Elk connector event moet source system, source object, source event type, source timestamp met timezone, idempotency reference en een normalized payload commitment bevatten.

Marketplace APIs

Marketplace APIs sturen marketplace.attesto.eu. De public catalog is read-only. Tenant acquisition, install, artifact download en revoke vereisen een authenticated tenant session plus CSRF. Publisher signup, profile management, developer checkout, payout onboarding en asset submission gebruiken een apart marketplace-only developer account. Publieke docs laten private Attesto review- en publication-endpoints bewust weg.

Public status API

status.attesto.eu exposeert customer-safe health voor publieke services. Het bevat component status, latency, uptime bars, incident summaries, generated time en timezone metadata. Het exposeert geen private admin status, tenant identifiers, logs, secrets, provider payloads of raw database details.

• GET https://status.attesto.eu/health retourneert status-service health.
• GET https://status.attesto.eu/api/status retourneert de public status payload die de page gebruikt.
• GET https://status.attesto.eu/v1/status is de versioned status payload alias.

Zie Public status page voor het publieke visibility model en component list.

Verification behavior

Verification faalt gesloten bij malformed objects, changed payloads, changed sequence numbers, removed of inserted events, stale checkpoints, wrong witness signatures, wrong anchors en ambiguous fork evidence.

Truth Package downloads en verificatie zijn aparte lifecycle events. Een download legt truth_package.accessed vast, wat bewijst dat het package is geserveerd. Een succesvol verifier report dat naar /v1/exports/{exportId}/truth-package/verify wordt gestuurd, legt truth_package.verified vast en bewijst dat een verifier de package hash, manifest hash en included artifacts heeft gecontroleerd. De uiteindelijke ZIP hash wordt vastgelegd nadat de ZIP bytes finalized zijn en wordt niet terug in dezelfde ZIP ingebed; zo vermijden we circular self-reference terwijl de downloadbare bytes zelfstandig hashbaar blijven.

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