Zum Hauptinhalt springen
POST
Attestierung prägen
Signiert eine Nutzlast mit dem verfügbaren Signaturschlüssel eines Ausstellers und zeichnet die resultierende Bestätigung auf. Ausstellerrichtlinien, Schlüsselstatus, Umgebung und Nutzungslimits können das Prägen verhindern.

Einen Datensatztyp auswählen

Für einen strukturierten Datensatz wählen Sie schema aus dem Dropdown-Menü für den Datensatztyp und geben Sie ein JSON-Objekt in claims ein. Lassen Sie payload_b64url leer. Der Server serialisiert diese Felder in die signierte JSON-Nutzlast. Dies identifiziert den Datensatztyp; es stellt nicht unabhängig fest, dass die Behauptungen wahr sind.

Ein Verifizierungspaket auswählen

Verifizierungspakete gehören zu Ihrem Arbeitsbereich. Verwenden Sie den Selektor unten mit derselben Umgebung und demselben API-Schlüssel wie „Ausprobieren“, und kopieren Sie dann die ausgewählte ID in pack_id. Lassen Sie dieses Feld für einen eigenständigen Datensatz weg. Sie können auch Verifizierungspakete auflisten oder In Console prägen verwenden.

Eine bestehende Nutzlast verwenden

Wenn Sie die genauen zu signierenden Bytes bereits haben, lassen Sie schema und claims weg. Kodieren Sie die ursprünglichen Bytes als ungepolstertes base64url in payload_b64url. Für JSON serialisieren Sie das Objekt zuerst. Anwendungsfelder wie subject, claims und schema gehören in diese kodierten Bytes; verwenden Sie sie entweder über die oben genannte strukturierte Eingabe oder innerhalb der kodierten Bytes, niemals beides. Dieser Endpunkt überprüft nicht unabhängig die Wahrheit der eingereichten Behauptungen oder validiert beliebige Anmeldeinformationsschemata. Verwenden Sie den kid des Schlüssels und den passenden alg. Die Registrierung eines öffentlichen Schlüssels allein macht keinen privaten Signierschlüssel verfügbar. Siehe Ausstellerschlüssel.

Optionaler Ablauf

Für strukturierte schema und claims setzen Sie expires_at_unix auf einen zukünftigen Unix-Zeitstempel in Sekunden. Truthlocks fügt ihn an der Wurzel der signierten JSON-Nutzlast ein. Mit payload_b64url platzieren Sie dieses Feld innerhalb der exakten JSON-Nutzlast, bevor Sie es kodieren, und lassen Sie das separate Anforderungsfeld weg. Nach diesem Zeitpunkt gibt die Verifizierung EXPIRED zurück. Das Ablaufdatum kann nicht von einem bestehenden signierten Datensatz verlängert oder entfernt werden; erstellen Sie einen Ersatz. Lassen Sie es weg, wenn Sie kein Ablaufdatum für die Bestätigung wünschen. Daten innerhalb einzelner Ansprüche, wie z. B. ein Reisepass expiry_date, sind separate Ansprüche und legen das Ablaufdatum der Bestätigung nicht automatisch fest. Bestehenden Datensätzen wird kein Datum rückwirkend zugewiesen. Behalten Sie die genaue Nutzlast und den Ablauf bei Wiederholungsversuchen bei. Ein idempotenter Wiederholungsversuch gibt den ursprünglichen Datensatz auch nach dessen Ablauf zurück.

Sichere Wiederholung

Idempotency-Key ist erforderlich. Generieren Sie einen Wert pro beabsichtigter Prägung und bewahren Sie ihn zusammen mit der ursprünglichen Anfrage für Wiederholungen auf. Verwenden Sie ihn nicht für verschiedene Inhalte wieder.

Dokumentintegrität

Der gespeicherte Dokument-Hash wird in dieser Reihenfolge ausgewählt:
  1. claims.document.sha256 innerhalb einer JSON-Nutzlast.
  2. Der document_hash der Anfrage.
  3. SHA-256 der dekodierten Nutzlast-Bytes.
Ein eingebetteter Hash hat Vorrang vor dem separaten Feld. Fügen Sie den Hash in die signierte Nutzlast ein, wenn Sie diesen Anspruch an die Signatur binden müssen. Ein übermittelter Hash ist eine Behauptung über eine Datei; der Server kann den Inhalt der Datei nicht allein aus dem Hash ermitteln. Übergeben Sie document_hash_hex an verification, um einen Dateihash zu vergleichen. Behalten Sie die ursprüngliche Nutzlast für die Nutzlast-Integritätsprüfung bei.

Antwort und Lieferung

HTTP 201 gibt attestation_id, issued_at_unix, signature und log zurück. Die Log-Position ist log.leaf_index, nicht ein Top-Level log_index. recipient_email fordert eine asynchrone Benachrichtigung an. HTTP 201 bestätigt die Prägung, nicht die E-Mail-Zustellung. Lassen Sie es weg, wenn Sie den Datensatz selbst verteilen. Ein Beispiel für eine Anfrage mit den tatsächlichen Eingabe- und Antwortfeldern finden Sie im Schnellstart.

Feldhandbuch für Datensatztypen

Diese Felder sind vorgeschlagene Anspruchsstrukturen, keine Garantie für die Anspruchsvalidierung oder Identitätsprüfung.

Autorisierungen

X-API-Key
string
header
erforderlich

API-Schlüssel für die Maschine-zu-Maschine-Authentifizierung

Header

Idempotency-Key
string
erforderlich

Behalten Sie denselben Wert und Anforderungsbody bei, wenn Sie eine Prägung erneut versuchen.

Body

application/json

Wählen Sie „Strukturierter Datensatz“, um einen Datensatztyp auszuwählen und Ansprüche einzugeben, oder „Kodierte Nutzlast“, um vorhandene Bytes zu signieren. Kombinieren Sie niemals beide Eingabeformate.

alg
enum<string>
erforderlich

Muss dem ausgewählten Aussteller-Signaturschlüssel entsprechen.

Verfügbare Optionen:
Ed25519,
ES256,
ES384,
ES512,
RS256,
RS384,
RS512,
PS256,
PS384,
PS512
issuer_id
string<uuid>
erforderlich

Die UUID des Ausstellers, der die Attestierung erstellt

Beispiel:

"550e8400-e29b-41d4-a716-446655440000"

kid
string
erforderlich

Schlüsselbezeichner für den Signierschlüssel

Beispiel:

"es256-key-1"

schema
enum<string>
erforderlich

Datensatztyp für strukturierte Eingaben. Geben Sie Ansprüche an und lassen Sie payload_b64url weg. Dieses Label validiert die Wahrheit der Ansprüche nicht unabhängig.

Verfügbare Optionen:
verifiable-id,
passport,
drivers-license,
government-id,
self-sovereign-id,
employment-verification,
professional-role,
membership-card,
professional-certification,
license,
accreditation,
degree,
completion-cert,
course-credit,
transcript,
micro-credential,
training-completion,
medical-license,
dea-registration,
board-certification,
health-credential,
vaccination-record,
aml-kyc,
security-clearance,
sam-gov,
jurisdiction-approval,
attestation-of-will,
bank-verification,
credit-attestation,
income-verification,
skill-badge,
competency,
industry-cert,
product-authenticity,
chain-of-custody,
origin-verification,
custom,
attestation
Beispiel:

"verifiable-id"

claims
object
erforderlich

Strukturierte Datensatzfelder. Erforderlich mit Schema; kann nicht mit payload_b64url kombiniert werden.

Beispiel:
attestation_id
string
content_type
string

MIME-Typ der ursprünglichen Bytes, wie application/json, application/pdf oder image/png. Strukturierte Schema-/Anspruchseingaben erfordern application/json.

Beispiel:

"application/json"

document_hash
string

Optionaler hexadezimaler SHA-256-Dokument-Hash. Ein eingebetteter claims.document.sha256 hat Vorrang; andernfalls wird dieses Feld verwendet, dann der dekodierte Nutzlast-Hash.

pack_id
string<uuid>

Optionale UUID des Workspace-Verifizierungspakets. Verwenden Sie „Verifizierungspakete auflisten“ mit demselben API-Schlüssel, um ein vorhandenes aktives Paket auszuwählen; lassen Sie es für einen eigenständigen Datensatz weg.

expires_at_unix
integer<int64>

Optionaler zukünftiger Unix-Zeitstempel in Sekunden für strukturierte Schema-/Anspruchseingaben. Er ist in der signierten JSON-Nutzlast enthalten. Für die Eingabe payload_b64url lassen Sie dieses Anforderungsfeld weg und betten expires_at_unix stattdessen an der Wurzel der genauen JSON-Nutzlast ein. Das Ablaufdatum kann nicht nachträglich geändert werden.

Erforderlicher Bereich: 1 <= x <= 253402300799
recipient_email
string<email>

Optionaler Empfänger für asynchrone Benachrichtigungen nach dem Prägen. Eine erfolgreiche Prägeantwort bestätigt die Zustellung nicht.

Antwort

Bestätigung geprägt

attestation_id
string<uuid>
issuer_id
string<uuid>
version
string
status
string
expires_at_unix
integer<int64> | null

Aufgezeichneter signierter Ablauf in Unix-Sekunden; null bedeutet, dass kein Ablauf aufgezeichnet wird. Älteren Datensätzen wird kein neuer Ablauf zugewiesen.

issued_at_unix
integer<int64>
payload_hash
string
signature
object
log
object
governance
object | null