Zurück zum Entwicklerportal (Developer Portal)
API-Referenz (API Reference)

Trusteddit-Registrierungs-API (Enrollment API)

Basis-URL: https://enroll.trusteddit.com

Authentifizierung (Authentication)

Alle API-Anfragen müssen ein gültiges Amazon-Cognito-ID-Token im Authorization-Header enthalten. Tokens werden vom Cognito User Pool Ihrer App ausgestellt und laufen nach 1 Stunde ab.

Authorization: Bearer <cognito-id-token>
Content-Type: application/json

Die Trusteddit-Registrierungs-API validiert die JWT-Signatur gegen die öffentlichen Schlüssel Ihres Cognito User Pools. Stellen Sie sicher, dass Ihre Variablen COGNITO_USER_POOL_ID und COGNITO_CLIENT_ID beim Onboarding Ihrer Plattform bei Trusteddit hinterlegt sind.

Ratenbegrenzungen (Rate Limits)

LimitWert (Value)Geltungsbereich (Scope)Hinweise (Notes)
Registrierungen pro Tag (Enrollments per day)10Pro authentifiziertem BenutzerWird um 00:00 UTC zurückgesetzt
Anfragen pro Minute (Requests per minute)60Pro Plattform-API-SchlüsselGilt über alle Endpunkte hinweg
Statusprüfung (Health check)Unbegrenzt (Unlimited)Pro IP-AdresseKeine Authentifizierung erforderlich

Wird eine Ratenbegrenzung überschritten, antwortet die API mit HTTP 429 und einem Retry-After-Header, der die Wartezeit in Sekunden bis zum nächsten Versuch angibt.

POST

/api/v1/enroll

Übermitteln Sie eine PKCS#10-Zertifikatsignieranforderung (Certificate Signing Request, CSR), um ein Gerätezertifikat von der Trusteddit-Zertifizierungsstelle (CA) zu erhalten. Der CSR muss ECDSA P-256 nutzen und eine opake Signer-ID als allgemeinen Namen (Common Name, CN) enthalten.

Anfragekörper (Request Body)

// Content-Type: application/json
{
  "csr": "-----BEGIN CERTIFICATE REQUEST-----\n..."
  // PEM-encoded PKCS#10 CSR
  // Subject CN must be in format: ph_<hex16>@thephenom.app
  // Key algorithm: EC / P-256 (ECDSA)
  // Signature algorithm: ES256 (ECDSA with SHA-256)
}

Antwort: 201 Created

{
  "certificate": "-----BEGIN CERTIFICATE-----\n...",
  // PEM-encoded device certificate
  // CN: ph_<hex16>@thephenom.app
  // Issuer: Trusteddit-Journalist-Issuer-CA
  // Algorithm: ES256 (ECDSA P-256)
  // Validity: 90 days from issuance

  "chain": [
    "-----BEGIN CERTIFICATE-----\n...",  // Trusteddit-Journalist-Issuer-CA
    "-----BEGIN CERTIFICATE-----\n..."   // Trusteddit Intermediate CA
  ],
  // Full CA chain, ordered from issuing CA to intermediate.
  // Append to certificate when constructing the C2PA manifest.

  "expiresAt": "2026-07-01T00:00:00Z",
  // ISO 8601 UTC expiry of the device certificate.
  // Schedule re-enrollment before this date.

  "signerId": "ph_a3f92c1d8b4e7f06@thephenom.app",
  // Echo of the signer ID extracted from the CSR CN.
  // Confirm this matches what you submitted.

  "serialNumber": "3a:9f:c2:1d:..."
  // Hex-encoded certificate serial number.
  // Store this to correlate with revocation records if needed.
}

Antwort: 4xx / 5xx Fehler

{
  "code": "INVALID_CSR_FORMAT",
  // Machine-readable error code – see Error Codes table below
  "message": "CSR signature verification failed",
  // Human-readable explanation
  "requestId": "req_01hvmk..."
  // Opaque request ID – include in support emails
}
GET

/api/v1/health

Gibt den Betriebsstatus der Registrierungs-API und der vorgelagerten CA-Infrastruktur zurück. Keine Authentifizierung erforderlich. Geeignet für Verfügbarkeitsüberwachung und Vorab-Prüfungen (pre-flight checks) in Ihrer App.

// 200 OK – all systems operational
{
  "status": "ok",
  "ca": "reachable",
  "version": "1.0.3",
  "timestamp": "2026-04-03T12:00:00Z"
}

// 503 Service Unavailable – CA unreachable or degraded
{
  "status": "degraded",
  "ca": "unreachable",
  "message": "CA signing endpoint is not responding",
  "timestamp": "2026-04-03T12:00:00Z"
}

Fehlercodes (Error Codes)

CodeHTTPBeschreibung (Description)Lösung (Resolution)
AUTH_FAILED
401
Der Authorization-Header fehlt, ist fehlerhaft oder das JWT ist abgelaufen / ungültig.Authentifizieren Sie den Benutzer erneut über Cognito und wiederholen Sie die Anfrage mit einem neuen ID-Token.
MISSING_CSR
400
Der Anfragekörper enthält kein "csr"-Feld oder das Feld ist leer.Stellen Sie sicher, dass der JSON-Körper einen PEM-codierten CSR im Schlüssel "csr" enthält.
INVALID_CSR_FORMAT
422
Der CSR konnte nicht verarbeitet werden, die Signatur ist ungültig oder der Algorithmus ist nicht ES256/P-256.Erzeugen Sie den CSR erneut mit @peculiar/x509 und ECDSA P-256. Prüfen Sie, ob der CSR PEM-codiert ist (beginnt mit "-----BEGIN CERTIFICATE REQUEST-----").
RATE_LIMITED
429
Der authentifizierte Benutzer hat das Limit von 10 Registrierungsanfragen innerhalb von 24 Stunden überschritten.Warten Sie, bis das Zeitfenster zurückgesetzt wird (siehe Retry-After-Header), bevor Sie es erneut versuchen.
CA_ERROR
502
Die Trusteddit-Zertifizierungsstelle (CA) hat beim Signieren des Zertifikats einen internen Fehler festgestellt.Wiederholen Sie die Anfrage mit exponentiellem Backoff. Bleibt der Fehler bestehen, wenden Sie sich an developers@trusteddit.com.

Zertifikatsdetails (Certificate Details)

Eigenschaft (Property)Wert (Value)
Algorithmus (Algorithm)ES256 (ECDSA with SHA-256)
Schlüsseltyp (Key Type)EC / P-256 (secp256r1 / prime256v1)
Gültigkeitsdauer (Validity Period)90 Tage ab Ausstellungszeitpunkt
Format des Subject-CN (Subject CN Format)ph_<hex16>@thephenom.app
Aussteller-CN (Issuer CN)Trusteddit-Journalist-Issuer-CA
Schlüsselverwendung (Key Usage)Digital Signature
Erweiterte Schlüsselverwendung (Extended Key Usage)id-kp-contentCommitment (C2PA)
Grundlegende Einschränkungen (Basic Constraints)CA:FALSE
OCSP-Responderhttps://ocsp.trusteddit.com
CRL-Verteilungspunkt (CRL Distribution Point)https://crl.trusteddit.com/issuer.crl

Vertrauenskette (Trust Chain)

Trusteddit stellt Gerätezertifikate über die Journalist Issuer CA aus, die über die Trusteddit Intermediate CA mit einer von der C2PA-Vertrauensliste (C2PA Trust List) anerkannten Root-CA verknüpft ist. Prüfende Anwendungen lösen diese Kette bei der Überprüfung von C2PA-Manifesten automatisch auf.

1
Trusteddit Root CA
root

Von Trusteddit betriebene Stammzertifizierungsstelle (Root CA), Anker der Vertrauenskette

2
Trusteddit Intermediate CA
intermediate

Von Trusteddit betriebene Zwischenzertifizierungsstelle (ES256, 3 Jahre Gültigkeit)

3
Trusteddit-Journalist-Issuer-CA
issuer

Ausstellende CA für gerätebezogene Zertifikate (ES256, 1 Jahr Gültigkeit)

4
Gerätezertifikat (Device Certificate)
end-entity

Pro-Installation-Zertifikat für Ihre Anwendung (ES256, 90 Tage Gültigkeit)

Die vollständige Vertrauenskette (Gerätezertifikat + ausstellende CA + Zwischen-CA) ist im Feld chain der Registrierungsantwort enthalten. Binden Sie diese Kette in die Signaturinformationen Ihres C2PA-Manifests ein, damit prüfende Anwendungen den vollständigen Pfad zum Vertrauensanker ohne zusätzliche HTTP-Anfragen auflösen können.

Infrastruktur-Leitfaden (Infrastructure Guide)