Zum Inhalt

Stempel verifizieren

Prüft die Gültigkeit eines Zeitstempels anhand seiner Token-ID. Dieser Endpoint ist öffentlich und benötigt keine Authentifizierung.

Endpoint

GET /api/v1/verify/v1/token/{token_id}

Auth: Keine (öffentlicher Endpoint)

Pfad-Parameter

Parameter Typ Beschreibung
token_id UUID Die Token-ID aus der Stamp-Response

Beispiel-Request

curl https://siegel.kavra.cloud/api/v1/verify/v1/token/550e8400-e29b-41d4-a716-446655440000

Response (200 OK) - Gültiger Stempel

{
  "valid": true,
  "token_id": "550e8400-e29b-41d4-a716-446655440000",
  "issued_at": "2026-05-14T12:00:00Z",
  "content_sha256": "a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4",
  "tsp_provider": "mock",
  "is_qualified": false,
  "reason": null
}

Response (200 OK) - Ungültiger/Unbekannter Token

{
  "valid": false,
  "token_id": null,
  "issued_at": null,
  "content_sha256": null,
  "tsp_provider": null,
  "is_qualified": null,
  "reason": "Token nicht gefunden"
}

Kein 404

Der Verify-Endpoint gibt bei unbekannten Tokens 200 OK mit valid: false zurück, nicht 404. So kann ein Aufrufer den Token-Status prüfen, ohne HTTP-Fehlercodes auswerten zu müssen.

Response-Felder

Feld Typ Beschreibung
valid boolean true wenn der Stempel gültig ist
token_id UUID? Token-ID (nur bei gültigem Stempel)
issued_at datetime? Erstellungszeitpunkt UTC
content_sha256 string? SHA-256-Hash des gestempelten Inhalts
tsp_provider string? TSP-Provider (mock, signius, ...)
is_qualified boolean? Qualifizierungsstatus
reason string? Begründung bei valid: false

Alternativer Endpoint: Raw-Token-Verifikation

Neben der ID-basierten Verifikation gibt es auch eine Verifikation über das opake Token:

POST /api/v1/verify/v1/raw

{
  "token": "MIIBxjAOBgorBgEE..."
}

Dieser Endpoint erwartet den opaken Token-String (das token-Feld aus der Stamp-Response) und prüft dessen Gültigkeit.

Beispiel mit Python SDK

from kavra_siegel import SiegelClient

client = SiegelClient(
    base_url="https://siegel.kavra.cloud",
    service_token="sk_your_token_here",
)

# Verify benötigt kein Auth, nutzt aber den Client für Error-Handling
from uuid import UUID
result = await client.verify_token(
    UUID("550e8400-e29b-41d4-a716-446655440000")
)

if result.valid:
    print(f"Gültig seit {result.issued_at}")
    print(f"Qualifiziert: {result.is_qualified}")
else:
    print(f"Ungültig: {result.reason}")

Jeder Stamp enthält eine verify_url. Diesen Link können Sie an Dritte weitergeben:

https://siegel.kavra.cloud/api/v1/verify/v1/token/550e8400-e29b-41d4-a716-446655440000

Der Empfänger kann die Echtheit und den Zeitpunkt des Stempels ohne Account oder API-Key prüfen.