API

Public API

Production API origin dla SDKs i public verification to https://verify.attesto.eu. Tenant browser workflows są na https://dashboard.attesto.eu.

Wybierz właściwą API family

Attesto ma wiele public surfaces, ponieważ evidence work dzieje się w różnych miejscach. Użyj SDK/API z serwera do tworzenia evidence, webhooks do odbierania lifecycle notifications, connectors do przechwytywania source-system observations oraz verifier endpoints, gdy inny system musi sprawdzić evidence przed zaufaniem jej.

Surface	Użyj gdy	Primary routes	Credential
v1 SDK Events	Potrzebujesz stable event logging, receipts, anchoring i exports.	`/v1/sdk/events`, `/v1/sdk/events/batch`, `/v1/events/{id}/proof`, `/v1/exports/{id}/truth-package/verify`	Tenant system key albo tenant auth, zależnie od route.
v2 Proofstream	Potrzebujesz ordered streams, receipts, windows, checkpoints, witnesses, anchors i bundles.	`/v2/streams`, `/v2/streams/{id}/events`, `/v2/checkpoints/{id}`	Tenant system key dla server ingest; tenant session dla dashboard views.
Verifier API	Otrzymujesz evidence i musisz ją sprawdzić przed poleganiem na niej.	`/v2/verify`, `/v1/public/verify`	Brak tenant cookie dla public proof objects.
Audit packs	Potrzebujesz portable evidence bundle dla workflow auditora albo regulatora.	`/v2/audit/packs`, `/v2/tenant/audit/packs`	Tenant auth/system policy.
Connectors	Zewnętrzny source system emituje evidence do Attesto.	`/v2/connectors/signed-webhooks/{id}/events`, `/v2/connectors/repository-webhooks/{id}/events`	Connector-specific signed envelope.
Marketplace	Potrzebujesz public connector catalog, tenant installs, developer accounts, publisher billing albo asset submission.	`/v1/marketplace/items`, `/v1/marketplace/auth/`, `/v1/marketplace/publisher/`	Public read-only, tenant session albo marketplace developer session zależnie od route.
Identity i settings	Tenant user loguje się, akceptuje invite albo konfiguruje enterprise SSO.	`/v1/auth/discover`, `/v1/auth/external/start`, `/v1/settings/identity-providers`	Tenant browser session i CSRF dla settings; krótkotrwały login state dla SSO.
Public status	Potrzebujesz customer-safe component health, latency, uptime bars i incident state.	`/api/status`, `/v1/status`	Public, secret-free status payload.

Origins

Origin	Cel
`https://verify.attesto.eu`	Public API, health, signing public key, v1 proof verification, v2 Proofstream verification.
`https://dashboard.attesto.eu`	Tenant dashboard, system registration, key reveal-once, exports, webhooks, connectors, billing.
`https://audit.attesto.eu`	Auditor-facing portal dla invited external auditors.
`https://status.attesto.eu`	Customer-safe service status API i status page. Private admin control panel jest celowo wykluczony.

Authentication

Server-side event ingest używa tenant system key w headerze Authorization: Bearer. Public verification routes walidują dostarczone proof objects i nie wymagają tenant cookies. Tenant dashboard routes używają istniejącej secure browser session oraz CSRF recovery dla mutating requests. Nie umieszczaj system keys ani SSO client secrets w 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 logują się przez email discovery na dashboard.attesto.eu. Attesto zwraca jeden zalecany next step zamiast pokazywać wszystkich providers naraz. Marketplace developer accounts, admin staff auth i auditor auth pozostają oddzielnymi surfaces.

Route	Cel	Security notes
`POST /v1/auth/discover`	Przyjmuje email i opcjonalny invite token, a następnie zwraca password, OAuth/OIDC, SAML, organization SSO albo signup/trial jako next step.	Nie ujawnia provider wall ani secret provider config.
`GET /v1/auth/providers`	Zwraca safe provider labels dla enabled login paths.	Bez client secrets i private metadata.
`POST /v1/auth/external/start`	Tworzy OAuth/OIDC state, nonce i PKCE data, a następnie zwraca redirect URL dla discovered provider.	State jest krótkotrwały i single-use.
`GET /v1/auth/external/callback/{provider_id}`	Weryfikuje provider callback i wydaje istniejące tenant session cookies.	Issuer, audience, nonce, JWKS i verified email są sprawdzane.
`GET /v1/auth/saml/metadata/{provider_id}`	Zwraca tenant-specific SAML SP metadata dla enterprise setup.	Bezpieczne do udostępnienia tenant identity provider.
`POST /v1/auth/saml/acs/{provider_id}`	Przetwarza signed SAML assertions.	Odrzuca unsigned, replayed, expired, wrong-audience i wrong-recipient assertions.
`POST /v1/auth/login`, `POST /v1/auth/signup`	Password fallback i czyste signup/trial creation po tym, gdy discovery zaleci tę ścieżkę.	Password fallback pozostaje scoped do tenant dashboard users; marketplace developer accounts są osobne.
`GET /v1/auth/invite/{token}`	Zwraca invite context dla email-first acceptance flow.	Invite token jest walidowany przed identity linking.
`POST /v1/auth/accept-invite`	Akceptuje invite z password setup albo provider-based activation.	External linking wymaga verified email i tenant match.
`POST /v1/auth/refresh`, `POST /v1/auth/logout`, `GET /v1/auth/csrf`, `GET /v1/auth/me`	Session refresh, logout, CSRF recovery i current user identity.	Używaj browser credentials; nigdy nie loguj session cookies.

Zobacz Tenant SSO dla guide konfiguracji Entra ID, generic OIDC i SAML.

Source time i timezone policy

Attesto zapisuje, kiedy source system twierdzi, że event się wydarzył, oraz kiedy Attesto go odebrało. Event APIs wymagają timezone-aware timestamps, takich jak 2026-06-07T12:00:00+02:00 albo 2026-06-07T10:00:00Z. Tenant timezone jest konfigurowalna; systems domyślnie dziedziczą tenant timezone i mogą ustawić własne source_timezone, gdy podłączone źródło działa w innej jurysdykcji.

Field	Meaning	Requirement
`occurred_at`	Source-system event time.	Wymagane dla Proofstream events i musi zawierać timezone albo UTC offset.
`source_timezone`	IANA timezone dla zarejestrowanego source system.	Domyślnie z tenant timezone; używaj wartości takich jak `Europe/Amsterdam` albo `Europe/Berlin`.
Connector received time	Kiedy Attesto albo Local Vault odebrał source event.	Ustawiane przez receiving service, nie przez untrusted frontend code.
Normalized UTC time	Canonical comparison time dla verification i ordering.	Wyliczane server-side przy zachowaniu source context.

Idempotency i replay behavior

Write routes akceptują Idempotency-Key. Powtórzenie tej samej key z tym samym canonical request zwraca oryginalny result. Powtórzenie tej samej key z innym request kończy się konfliktem. To chroni connector retries i server-side job retries przed tworzeniem duplikatów evidence.

Case	Result
Same key, same request	Original response jest replayed.
Same key, changed payload	`409 Conflict`.
No key on write path	Request jest odrzucany, gdy route wymaga dedupe.

v1 event ingest

Użyj v1, gdy potrzebujesz stable event audit trail i anchoring path. SDKs ustawiają defaults dla event type, status, retries i idempotency.

POST /v1/sdk/events loguje jeden event.
POST /v1/sdk/events/batch loguje do 1000 events.
GET /v1/events/{eventId}/proof zwraca anchored proof material dla event.
POST /v1/public/verify weryfikuje v1 proof object.
POST /v1/exports/{exportId}/truth-package/verify zapisuje backend-validated event truth_package.verified, gdy verifier report dowodzi, że wyeksportowany package został sprawdzony kryptograficznie.

Tenant dashboard v1 APIs

Te browser APIs obsługują dashboard.attesto.eu. Mutating calls używają tenant session cookies i CSRF recovery. Używaj system keys i SDK routes do server-side ingest; tych routes używają tenant operators zarządzający workspace.

Route family	Cel	Credential
`GET /v1/dashboard`	Zwraca tenant dashboard summary używane przez operator UI.	Tenant session.
`GET/POST /v1/systems`, `PATCH/DELETE /v1/systems/{system_id}`, `POST /v1/systems/{system_id}/rotate-key`	Rejestruje source systems, zachowuje source timezone policy i jednorazowo ujawnia albo rotuje system keys.	Tenant session; writer role dla mutations.
`GET /v1/events`, `GET /v1/events/{event_id}`, `GET /v1/events/{event_id}/proof`	Inspect tenant events i proof material.	Tenant session.
`POST /v1/events/{event_id}/retrieve`, `GET /v1/events/{event_id}/retrieve/status`	Startuje i monitoruje archive retrieval dla archived event evidence.	Tenant session; writer role do startu retrieval.
`GET/POST/DELETE /v1/exports`, `POST /v1/exports/{export_id}/download/prepare`, `GET /v1/exports/{export_id}/download?ticket=...`, `POST /v1/exports/{export_id}/truth-package/verify`	Tworzy, pobiera, usuwa i zapisuje verification record dla Truth Package exports.	Tenant session; writer role dla creation, deletion i verification record submission.
`GET/POST/PATCH/DELETE /v1/webhooks`, `POST /v1/webhooks/{webhook_id}/rotate-secret`, `GET /v1/webhooks/{webhook_id}/deliveries`	Zarządza signed tenant webhooks, rotuje one-shot delivery secret i inspect delivery attempts.	Tenant session; admin role dla webhook mutations.
`GET/POST/PATCH/DELETE /v1/users`, `POST /v1/users/{user_id}/resend-invite`	Zaprasza tenant users, ponownie wysyła invites, aktualizuje roles/status i revoke access.	Tenant session; owner/admin role dla mutations.
`GET/POST/PATCH/DELETE /v1/parties`	Utrzymuje external party records używane w tenant evidence workflows.	Tenant session; admin role dla mutations.
`GET /v1/packs`, `POST /v1/packs/{vertical_id}/install`, `DELETE /v1/packs/{vertical_id}`	Listuje, instaluje i usuwa tenant evidence packs bez tworzenia syntetycznych danych seed.	Tenant session; admin role dla install/remove.
`GET /v1/billing/plan`, `POST /v1/billing/checkout`, `POST /v1/billing/portal`	Odczytuje aktywny plan, startuje Stripe Checkout dla subscriptions Starter/Growth/Realtime z 30-dniowym trialem albo otwiera Stripe billing portal.	Tenant session; admin role dla checkout i portal sessions.
`GET/POST /v1/auditor-invites`, `POST /v1/auditor-invites/{access_id}/revoke`	Nadaje, listuje i cofa external auditor access do read-only audit portal.	Tenant session; admin role dla grant/revoke.

Minimalne 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 dodaje append-only streams, signed receipts, windows, checkpoints, witness evidence, anchors, bundles i offline verification.

POST /v2/streams tworzy stream.
POST /v2/streams/{streamId}/events dodaje jeden event i zwraca signed receipt.
POST /v2/streams/{streamId}/events/batch dodaje wiele events z receipt results.
GET /v2/streams/{streamId}/head zwraca bieżący append-only stream head.
GET /v2/receipts/{eventId} zwraca zapisany receipt.
POST /v2/verify/receipt bezpośrednio weryfikuje jeden receipt object.
GET /v2/windows/{windowId} zwraca window evidence i inclusion material.
GET /v2/checkpoints/{checkpointId} zwraca checkpoint evidence.
GET /v2/checkpoints/{checkpointId}/consistency?from=... zwraca consistency evidence.
GET /v2/witness/policies/{policyId} zwraca witness policy używaną do quorum checks.
GET /v2/anchors/{anchorEpochId} zwraca anchor epoch evidence.
GET /v2/ivc/epochs/{ivcEpochId} zwraca Proof of Evolution epoch evidence.
POST /v2/audit/packs tworzy offline verifier bundle, gdy range ma wymagane witness i anchor evidence.
POST /v2/verify weryfikuje receipt, stream, checkpoint, consistency, anchor, IVC albo bundle objects.

Utwórz 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

Dodaj 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 i dashboard APIs

Tenant browser APIs pokazują ten sam evidence model w dashboardzie bez dawania frontendowi dostępu do server-side system keys. Mutating dashboard calls używają browser cookies i CSRF recovery.

Route family	Cel	Credential
`GET /v2/tenant/streams`, `GET /v2/tenant/streams/{stream_id}/events`	Listuje streams i pozwala inspect stream events widoczne dla tenant.	Tenant session.
`GET /v2/tenant/receipts/{stream_event_id}`	Pozwala inspect stored receipt dla tenant-visible stream event.	Tenant session.
`GET /v2/tenant/streams/{stream_id}/proof-state`, `/forks`, `/ivc/epochs`	Odczytuje proof health, fork evidence i Proof of Evolution epochs.	Tenant session.
`GET /v2/tenant/streams/{stream_id}/windows`, `/checkpoints`	Pozwala inspect closed windows i checkpoints dla stream.	Tenant session.
`POST /v2/tenant/audit/packs`	Tworzy tenant-authorized offline bundle dla auditor review.	Tenant session plus tenant policy.
`PUT /v2/tenant/witness/policies/{policy_id}`	Aktualizuje tenant witness policy z configured quorum rules.	Tenant session plus tenant policy permission.

Tenant settings i SSO APIs

Tenant settings są dostępne tylko dla authenticated tenant users z wymaganą rolą. Provider secrets są szyfrowane server-side i nigdy nie wracają do browser po zapisie.

Route	Cel
`GET /v1/settings`	Zwraca tenant settings snapshot, w tym safe identity-provider metadata.
`PATCH /v1/settings/tenant`	Aktualizuje tenant display settings, locale i timezone policy.
`GET /v1/settings/identity-providers`	Listuje tenant SSO providers i public setup values.
`POST /v1/settings/identity-providers`	Dodaje Entra ID, generic OIDC albo SAML provider configuration.
`PATCH /v1/settings/identity-providers/{provider_id}`	Aktualizuje enabled state, domains, issuer metadata albo rotated secrets.
`DELETE /v1/settings/identity-providers/{provider_id}`	Wyłącza i usuwa tenant identity provider.

Connector i Local Vault APIs

Connectors są production evidence sources. Tenant users konfigurują connector records w dashboardzie, a source systems publikują events przez provider-specific signed envelopes albo Local Vault relay. Każdy connector event musi zawierać source system, source object, source event type, source timestamp z timezone, idempotency reference i normalized payload commitment.

Route family	Cel	Credential
`GET/POST /v2/tenant/connectors/signed-webhooks`, `DELETE /v2/tenant/connectors/signed-webhooks/{connector_id}`	Tworzy, listuje i revoke generic signed webhook connectors. Connector secrets są zwracane tylko raz przy tworzeniu, jeśli dotyczy, i nigdy ponownie.	Tenant session.
`GET/POST /v2/tenant/connectors/s3-objects`, `DELETE /v2/tenant/connectors/s3-objects/{connector_id}`, `POST /v2/tenant/connectors/s3-objects/{connector_id}/commit`	Tworzy, listuje, revoke i commit S3/R2 object evidence connectors. Route commit zapisuje metadata i integrity bez proxy object content.	Tenant session.
`GET/POST /v2/tenant/connectors/repository-webhooks`, `DELETE /v2/tenant/connectors/repository-webhooks/{connector_id}`	Tworzy, listuje i revoke GitHub/GitLab repository webhook connectors.	Tenant session.
`POST /v2/connectors/signed-webhooks/{connector_id}/events`	Ingest signed webhook event z zewnętrznego source system.	Connector signed envelope.
`POST /v2/connectors/repository-webhooks/{connector_id}/events`	Ingest repository change evidence.	Provider webhook/signature contract.
`GET/POST /v2/tenant/local-vault/installations`, `DELETE /v2/tenant/local-vault/installations/{installation_id}`	Zarządza Local Vault edge installations i revoke edge credentials fail-closed.	Tenant session.
`POST /v2/tenant/local-vault/enrollment-tokens`	Tworzy krótkotrwały, single-use enrollment token; po utworzeniu przechowywany jest tylko hash tokenu.	Tenant session.
`POST /v2/local-vault/enroll`	Wymienia ważny enrollment token na installation credential i public installation metadata.	Single-use enrollment token.
`POST /v2/local-vault/installations/{installation_id}/events`	Relay encrypted-spool events z customer edge do Proofstream.	Local Vault installation credential.
`POST /v2/local-vault/installations/{installation_id}/witness/checkpoints`	Przesyła customer-side witness checkpoint statements, gdy witness mode jest enabled przez policy.	Local Vault witness credential.

Marketplace APIs

Marketplace APIs obsługują marketplace.attesto.eu. Public catalog jest read-only. Tenant acquisition, installation, artifact download i revocation wymagają authenticated tenant session plus CSRF. Publisher signup, profile management, developer checkout, payout onboarding i asset submission używają oddzielnego marketplace-only developer account. Public docs celowo pomijają prywatne endpointy Attesto review i publication.

Route family	Cel	Credential
`GET /v1/marketplace/categories`, `/developer-tiers`, `/items`, `/items/{slug}`	Browse public connector categories, developer tiers i validated public assets.	Public, read-only.
`POST /v1/marketplace/auth/signup`, `/auth/login`, `/auth/logout`, `GET /auth/csrf`, `/auth/me`	Tworzy i obsługuje marketplace-only developer accounts. Te konta nie mogą logować się do tenant dashboard.	Marketplace developer credentials/session.
`GET /v1/marketplace/me/entitlements`, `/me/installs`	Listuje connector entitlements i installs tenantu.	Tenant session.
`POST /v1/marketplace/items/{slug}/acquire`, `/install`, `/install/update`, `/revoke`	Acquire, install, update albo revoke tenant access do connector asset.	Tenant session i CSRF.
`GET /v1/marketplace/items/{slug}/artifact`	Pobiera connector manifest artifact po aktywacji entitlement.	Tenant session z active entitlement.
`GET /v1/marketplace/evidence/{receipt_id}`	Pobiera marketplace evidence receipt metadata dla tenant-visible marketplace actions.	Tenant albo marketplace session scoped do evidence tenant.
`GET/POST/PATCH /v1/marketplace/publisher/profile`	Tworzy, czyta i aktualizuje publisher profile metadata.	Marketplace developer session i CSRF dla writes.
`GET /v1/marketplace/publisher/billing-state`, `POST /publisher/upgrade`, `/publisher/billing-portal`	Sprawdza developer tier state, uruchamia Stripe Checkout dla paid developer tiers albo otwiera billing portal.	Marketplace developer session i CSRF dla writes.
`POST /v1/marketplace/publisher/payout/onboarding`, `/publisher/payout/status`	Uruchamia Stripe Connect payout onboarding i odświeża payout readiness dla paid connector publishing.	Marketplace developer session i CSRF.
`POST /v1/marketplace/publisher/assets`	Przesyła connector manifest do private Attesto review. Public listing nigdy nie jest automatyczny.	Marketplace developer session, CSRF i eligible developer tier dla paid assets.

Public status API

status.attesto.eu udostępnia customer-safe health dla publicznych services. Zawiera component status, latency, uptime bars, incident summaries, generated time i timezone metadata. Nie ujawnia private admin status, tenant identifiers, logs, secrets, provider payloads ani raw database details.

GET https://status.attesto.eu/health zwraca status-service health.
GET https://status.attesto.eu/api/status zwraca public status payload używany przez stronę.
GET https://status.attesto.eu/v1/status jest versioned status payload alias.

Zobacz Public status page dla public visibility model i component list.

Verification behavior

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

Truth Package downloads i verification są osobnymi lifecycle events. Download zapisuje truth_package.accessed, dowodząc, że package został zaserwowany. Poprawny verifier report przesłany do /v1/exports/{exportId}/truth-package/verify zapisuje truth_package.verified, dowodząc, że verifier sprawdził package hash, manifest hash i included artifacts. Finalny ZIP hash jest zapisywany po finalizacji ZIP bytes i nie jest osadzany z powrotem w tym samym ZIP; to zapobiega circular self-reference, zachowując niezależną hashowalność pobieralnych bytes.

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

Status	Meaning	Akcja integratora
`400`	Malformed request albo unsupported verifier object.	Popraw request shape i retry z nową idempotency key, jeśli body się zmieni.
`401`	Missing albo invalid system key.	Zrotuj albo przekonfiguruj server-side credential.
`403`	Authenticated key nie ma dostępu do tenant, system albo stream.	Sprawdź tenant/system assignment.
`404`	Object nie jest widoczny dla caller albo nie istnieje.	Potwierdź IDs i tenant scope.
`409`	Idempotency conflict, sequence conflict albo append conflict.	Nie retry blindly changed bodies; sprawdź conflict details.
`422`	Request syntactically valid, ale narusza route contract.	Popraw field values, policy references albo object kind.
`429`	Rate limit.	Back off z jitter i utrzymuj idempotency keys stabilne.
`5xx`	Service-side failure.	Retry z tą samą idempotency key i zachowaj oryginalny body.

API keys pozostają server-side

Attesto system keys to bearer credentials. Używaj ich tylko z trusted server-side processes, connector edges albo secret-managed job runners.