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/jsonDie 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)
| Limit | Wert (Value) | Geltungsbereich (Scope) | Hinweise (Notes) |
|---|---|---|---|
| Registrierungen pro Tag (Enrollments per day) | 10 | Pro authentifiziertem Benutzer | Wird um 00:00 UTC zurückgesetzt |
| Anfragen pro Minute (Requests per minute) | 60 | Pro Plattform-API-Schlüssel | Gilt über alle Endpunkte hinweg |
| Statusprüfung (Health check) | Unbegrenzt (Unlimited) | Pro IP-Adresse | Keine 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.
/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
}/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)
| Code | HTTP | Beschreibung (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-Responder | https://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.
Von Trusteddit betriebene Stammzertifizierungsstelle (Root CA), Anker der Vertrauenskette
Von Trusteddit betriebene Zwischenzertifizierungsstelle (ES256, 3 Jahre Gültigkeit)
Ausstellende CA für gerätebezogene Zertifikate (ES256, 1 Jahr Gültigkeit)
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.