Stempel erstellen

Erzeugt einen eIDAS-konformen Zeitstempel für einen SHA-256-Hash oder base64-encodierten Inhalt.

Endpoint

POST /api/v1/internal/v1/stamp

Auth: X-Kavra-Service-Token Header (erforderlich)

Request-Body

{
  "hash": "a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4",
  "tier": "basic",
  "metadata": {
    "source": "my-app",
    "document_ref": "contract-42"
  }
}

Felder

Feld	Typ	Pflicht	Beschreibung
`hash`	`string`	Eines von `hash`/`content_b64`	SHA-256-Hex, lowercase, exakt 64 Zeichen
`content_b64`	`string`	Eines von `hash`/`content_b64`	Base64-encodierter Inhalt, nur bei Tier `sealed` erlaubt
`tier`	`string`	Nein (Default: `basic`)	`basic`, `plus` oder `sealed`
`metadata`	`object`	Nein	Key-Value-Paare, werden gespeichert aber nicht signiert

Tiers

Tier	Beschreibung	Content-Upload
`basic`	Nur Hash wird gestempelt	Nicht erlaubt
`plus`	Hash + Verify-URL	Nicht erlaubt
`sealed`	Vollständiger Inhalt serverseitig gespeichert	Erlaubt (via `content_b64`)

Validierung

Entweder hash oder content_b64 muss angegeben werden (nicht beides weglassen)
content_b64 ist nur bei Tier sealed erlaubt
hash muss exakt 64 hexadezimale Zeichen enthalten (lowercase)

Response (201 Created)

{
  "token_id": "550e8400-e29b-41d4-a716-446655440000",
  "issued_at": "2026-05-14T12:00:00Z",
  "content_sha256": "a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4",
  "token": "MIIBxjAOBgorBgEE...",
  "tier": "basic",
  "tsp_provider": "mock",
  "is_qualified": false,
  "verify_url": "/api/v1/verify/v1/token/550e8400-e29b-41d4-a716-446655440000",
  "sealed_storage_url": null
}

Response-Felder

Feld	Typ	Beschreibung
`token_id`	`UUID`	Eindeutige ID des Stempels
`issued_at`	`datetime`	Zeitpunkt der Stempel-Erstellung (UTC)
`content_sha256`	`string`	SHA-256-Hash des gestempelten Inhalts
`token`	`string`	Opakes Token-Body (RFC-3161 Base64 bei echten TSPs)
`tier`	`string`	Genutzter Tier
`tsp_provider`	`string`	TSP-Provider-Name (`mock`, `signius`, ...)
`is_qualified`	`boolean`	`true` bei qualifiziertem TSP, `false` bei Mock
`verify_url`	`string`	Relativer Pfad zur Verifikation
`sealed_storage_url`	`string?`	Storage-URL bei Tier `sealed`, sonst `null`

Fehler

Status	Beschreibung
`401`	Service-Token fehlt oder ungültig
`422`	Validierungsfehler (Hash-Format, fehlende Felder, content_b64 bei falschem Tier)
`502`	TSP-Adapter konnte Stempel nicht erstellen

Beispiel mit Python SDK

from kavra_siegel import SiegelClient, StampTier

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

# Basic: nur Hash
token = await client.stamp_hash(
    sha256_hex="a1b2c3d4" * 8,
    tier=StampTier.BASIC,
)

# Sealed: mit Content
token = await client.stamp_content(
    content=b"Vertraulicher Inhalt",
    tier=StampTier.SEALED,
)