API

API publique

L'origin API de production pour les SDKs et la vérification publique est https://verify.attesto.eu. Les workflows navigateur tenant vivent sur https://dashboard.attesto.eu.

Choisir la bonne famille d'API

Attesto possède plusieurs surfaces publiques parce que le travail d'evidence se produit à différents endroits. Utilisez le SDK/API depuis votre serveur pour créer de l'evidence, les webhooks pour recevoir les lifecycle notifications, les connectors pour capturer les source-system observations, et les verifier endpoints lorsqu'un autre système doit vérifier l'evidence avant de lui faire confiance.

Origins

Authentication

L'event ingest server-side utilise une tenant system key dans le header Authorization: Bearer. Les public verification routes valident les proof objects fournis et ne nécessitent pas de tenant cookies. Les tenant dashboard routes utilisent la secure browser session existante plus CSRF recovery pour les mutating requests. Ne placez pas system keys ou SSO client secrets dans les 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

Les main tenant users se connectent via email discovery sur dashboard.attesto.eu. Attesto retourne un seul next step recommandé au lieu d'afficher tous les providers à la fois. Les marketplace developer accounts, admin staff auth et auditor auth restent des surfaces séparées.

Voir Tenant SSO pour le guide de setup Entra ID, generic OIDC et SAML.

Source time et timezone policy

Attesto enregistre le moment où le source system dit qu'un event s'est produit et le moment où Attesto l'a reçu. Les Event APIs exigent des timezone-aware timestamps comme 2026-06-07T12:00:00+02:00 ou 2026-06-07T10:00:00Z. Tenant timezone est configurable; les systems héritent par défaut de la tenant timezone et peuvent définir leur propre source_timezone lorsque la source connectée fonctionne dans une autre juridiction.

Idempotency et replay behavior

Les write routes acceptent Idempotency-Key. Répéter la même key avec la même canonical request retourne le résultat original. Répéter la même key avec une request différente échoue en conflict. Cela protège les connector retries et server-side job retries contre la création d'evidence dupliquée.

v1 event ingest

Utilisez v1 lorsque vous avez besoin du stable event audit trail et du anchoring path. Les SDKs définissent des defaults pour event type, status, retries et idempotency.

• POST /v1/sdk/events log un event.
• POST /v1/sdk/events/batch log jusqu'à 1000 events.
• GET /v1/events/{eventId}/proof retourne anchored proof material pour un event.
• POST /v1/public/verify vérifie un v1 proof object.
• POST /v1/exports/{exportId}/truth-package/verify enregistre un event backend-validated truth_package.verified après qu'un verifier report prouve que le package exporté a été vérifié cryptographiquement.

Tenant dashboard v1 APIs

Ces browser APIs alimentent dashboard.attesto.eu. Les appels mutating utilisent les tenant session cookies et CSRF recovery. Utilisez les system keys et SDK routes pour le server-side ingest; utilisez ces routes pour les tenant operators qui gèrent leur workspace.

Event body minimal:

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

• POST /v2/streams crée un stream.
• POST /v2/streams/{streamId}/events ajoute un event et retourne un signed receipt.
• POST /v2/streams/{streamId}/events/batch ajoute plusieurs events avec receipt results.
• GET /v2/streams/{streamId}/head retourne le stream head append-only actuel.
• GET /v2/receipts/{eventId} retourne le receipt stocké.
• POST /v2/verify/receipt vérifie directement un receipt object.
• GET /v2/windows/{windowId} retourne window evidence et inclusion material.
• GET /v2/checkpoints/{checkpointId} retourne checkpoint evidence.
• GET /v2/checkpoints/{checkpointId}/consistency?from=... retourne consistency evidence.
• GET /v2/witness/policies/{policyId} retourne la witness policy utilisée pour les quorum checks.
• GET /v2/anchors/{anchorEpochId} retourne anchor epoch evidence.
• GET /v2/ivc/epochs/{ivcEpochId} retourne Proof of Evolution epoch evidence.
• POST /v2/audit/packs crée un offline verifier bundle lorsque la range possède les witness et anchor evidence requis.
• POST /v2/verify vérifie receipt, stream, checkpoint, consistency, anchor, IVC ou bundle objects.

Créer 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

Ajouter 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 et dashboard APIs

Les Tenant browser APIs exposent le même evidence model dans le dashboard sans donner au frontend accès aux server-side system keys. Les mutating dashboard calls utilisent browser cookies et CSRF recovery.

Tenant settings et SSO APIs

Tenant settings est disponible seulement pour les authenticated tenant users avec le rôle requis. Les provider secrets sont chiffrés server-side et ne sont jamais renvoyés au browser après sauvegarde.

Connector et Local Vault APIs

Les connectors sont des production evidence sources. Les tenant users configurent les connector records dans le dashboard, tandis que les source systems postent des events via provider-specific signed envelopes ou Local Vault relay. Chaque connector event doit inclure source system, source object, source event type, source timestamp avec timezone, idempotency reference et normalized payload commitment.

Marketplace APIs

Les Marketplace APIs alimentent marketplace.attesto.eu. Le public catalog est read-only. Tenant acquisition, installation, artifact download et revocation nécessitent une authenticated tenant session plus CSRF. Publisher signup, profile management, developer checkout, payout onboarding et asset submission utilisent un compte marketplace-only developer séparé. Les docs publiques omettent volontairement les endpoints privés Attesto review et publication.

Public status API

status.attesto.eu expose une health customer-safe pour les services publics. Elle inclut component status, latency, uptime bars, incident summaries, generated time et timezone metadata. Elle n'expose pas private admin status, tenant identifiers, logs, secrets, provider payloads ni raw database details.

• GET https://status.attesto.eu/health retourne status-service health.
• GET https://status.attesto.eu/api/status retourne le public status payload utilisé par la page.
• GET https://status.attesto.eu/v1/status est l'alias versioned status payload.

Voir Public status page pour le public visibility model et la component list.

Comportement de vérification

La vérification fail-closed sur malformed objects, changed payloads, changed sequence numbers, removed ou inserted events, stale checkpoints, wrong witness signatures, wrong anchors et ambiguous fork evidence.

Les téléchargements Truth Package et la vérification sont des lifecycle events séparés. Un téléchargement enregistre truth_package.accessed, prouvant que le package a été servi. Un verifier report réussi soumis à /v1/exports/{exportId}/truth-package/verify enregistre truth_package.verified, prouvant qu'un verifier a contrôlé le package hash, le manifest hash et les artifacts inclus. Le hash ZIP final est enregistré après finalisation des bytes ZIP et n'est pas réintégré dans le même ZIP; cela évite une circular self-reference tout en gardant les bytes téléchargeables hashables indépendamment.

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