CodeB Playground · API

Playground-API

Alles, was die Playground-Seite kann, per Skript oder Build-Pipeline: Testorganisation registrieren, Zugangszertifikat für den eigenen Schlüssel abrufen, Registrierungszertifikat für das, was Sie abfragen oder ausstellen, und den einen Test-Vertrauensanker laden, den eine Wallet braucht. JSON über HTTPS, vier Aufrufe.

Nur für Tests. Die Zertifikate stammen von der CA unserer Testseite, Namen tragen das Wort TEST, nichts wird geprüft und nichts gilt in Produktion. Entwickelt nach dem EUDI Architecture and Reference Framework 3.0; eigene Einschätzung, nichts hier ist zertifiziert.

Authentifizierung

Melden Sie sich auf der Playground-Seite mit Ihrem CodeB-Konto an und erstellen Sie unter „API-Schlüssel“ einen Schlüssel. Er wird einmal angezeigt. Senden Sie ihn mit jedem Aufruf:

Authorization: Bearer pgk_...

01 · Testorganisation registrieren

POST/playground.ashx?op=org

Legt eine Relying Party, einen Aussteller oder beides in einem Eintrag an. Die Antwort enthält die id (pg- und zehn Hex-Ziffern), die Sie in allen weiteren Aufrufen verwenden.

FeldTypPflichtBedeutung
official_namestringjaOffizieller Name, höchstens 59 Zeichen. Wird als "TEST <Name>" gespeichert und angezeigt.
org_idstringjaOrganisationskennung, ein Testwert wie VATDE-123456789. 1 bis 64 Buchstaben, Ziffern, Leerzeichen und . / : + _ -
countrystringjaLändercode mit zwei Buchstaben, zum Beispiel DE.
rolesarrayja"verifier" (Relying Party), "issuer" oder beides.
emailstringjaKontakt-E-Mail-Adresse. Sie steht im Zertifikat.
trade_namestringName, der Nutzern angezeigt wird.
entitlementsarrayNur Aussteller: Non_Q_EAA_Provider (Standard), PID_Provider, QEAA_Provider, PUB_EAA_Provider.
url, support_url, privacy_policy, info_uristringhttps-Adressen Ihres Testdienstes.
phone, services, intended_usestringJe eine Zeile Text.
idstringMit der id einer bestehenden Testorganisation ändern Sie deren Kontaktdaten. Name, Kennung und Land sind nicht änderbar.
curl -s "https://phone.codeb.io/playground.ashx?op=org" \
  -H "Authorization: Bearer $PG_KEY" -H "Content-Type: application/json" \
  -d '{"official_name":"Example Bank","org_id":"VATDE-123456789","country":"DE",
       "roles":["verifier"],"email":"dev@example.com","url":"https://verifier.example.com"}'

Antwort

{"ok":true,"created":true,"id":"pg-3f9a1c0b7e",
 "organisations":[{"id":"pg-3f9a1c0b7e","official_name":"TEST Example Bank","org_id":"VATDE-123456789",
   "country":"DE","roles":["verifier"],"entitlements":["Service_Provider"],"status":"valid",
   "certificates":[],"trust_anchors":[]}]}

Nicht angenommen: Hostnamen, Adressen und E-Mail-Domains dieser Seite sowie Kennungen ihrer eigenen Einträge. Texte sind eine Zeile sichtbarer Zeichen.

02 · Zugangszertifikat für den eigenen Schlüssel

POST/playground.ashx?op=cert

Sie erzeugen den Schlüssel und senden eine Zertifikatsanforderung (PKCS#10, ECDSA P-256). Der private Schlüssel verlässt Ihren Rechner nie. Aus der Anforderung wird nur der öffentliche Schlüssel verwendet; die Namen im Zertifikat stammen aus Ihrer Testorganisation.

openssl ecparam -name prime256v1 -genkey -noout -out verifier.key
openssl req -new -key verifier.key -subj "/CN=playground" -out verifier.csr
FeldTypPflichtBedeutung
idstringjaIhre Testorganisation.
csrstringjaPKCS#10-Anforderung, PEM oder Base64-DER.
dnsarrayBis zu 10 Hostnamen Ihres Dienstes, für x509_san_dns.
daysnumberLaufzeit, 1 bis 30 (Standard 30).
curl -s "https://phone.codeb.io/playground.ashx?op=cert" \
  -H "Authorization: Bearer $PG_KEY" -H "Content-Type: application/json" \
  -d "$(jq -n --arg csr "$(cat verifier.csr)" \
        '{id:"pg-3f9a1c0b7e", csr:$csr, dns:["verifier.example.com"], days:30}')"

Antwort

{"ok":true,"test":true,"serial":"5d0c...","not_after":"2026-12-12T10:00:00Z",
 "certificate_pem":"-----BEGIN CERTIFICATE-----\n...","ca_pem":"-----BEGIN CERTIFICATE-----\n...",
 "x5c":["<certificate, base64 DER>","<CA certificate, base64 DER>"]}

Das Zertifikat folgt dem Profil von ETSI TS 119 411-8. Es trägt die Einheit „CodeB Playground TEST“ und die Kennzeichnungs-Richtlinie 2.25.195586870214937213748673734628273007303.99. x5c passt direkt in den Kopf Ihrer signierten Anfrage.

03 · Registrierungszertifikat für das, was Sie abfragen oder ausstellen

POST/playground.ashx?op=rc

Liefert ein rc-wrp+jwt nach ETSI TS 119 475, 30 Tage gültig, mit Statusverweis. Eine Relying Party sendet die DCQL-Abfrage, die sie Wallets präsentiert; das Zertifikat nennt genau diese Nachweise und Angaben.

Relying Party

curl -s "https://phone.codeb.io/playground.ashx?op=rc" \
  -H "Authorization: Bearer $PG_KEY" -H "Content-Type: application/json" \
  -d '{"id":"pg-3f9a1c0b7e","kind":"verifier","purpose":"Age check at checkout",
       "dcql_query":{"credentials":[{"id":"pid","format":"dc+sd-jwt",
         "meta":{"vct_values":["urn:eudi:pid:1"]},
         "claims":[{"path":["age_equal_or_over","18"]}]}]}}'

Aussteller

Ein Aussteller nennt die Attestierungstypen, die er ausstellt: dc+sd-jwt mit vct oder mso_mdoc mit doctype.

curl -s "https://phone.codeb.io/playground.ashx?op=rc" \
  -H "Authorization: Bearer $PG_KEY" -H "Content-Type: application/json" \
  -d '{"id":"pg-3f9a1c0b7e","kind":"issuer","attestations":[
       {"format":"dc+sd-jwt","vct":"https://issuer.example.com/vct/membership"},
       {"format":"mso_mdoc","doctype":"com.example.membership.1"}]}'

Antwort

{"ok":true,"test":true,"kind":"verifier","typ":"rc-wrp+jwt","exp":1797415200,
 "registration_certificate":"eyJ0eXAiOiJyYy13cnArand0Iiw..."}

exp ist eine Unix-Zeit. Der Inhalt trägt die private Angabe "codeb_playground": true, und seine registry_uri führt zu einem öffentlichen Eintrag mit "test": true.

04 · Wallet-Entwickler: ein Test-Vertrauensanker für alles hier

GET/wrpac-ca.ashx?ca&format=pem

Jedes Zugangszertifikat des Playground und das Zertifikat, das seine Registrierungszertifikate signiert, führen zu einer CA: der Zugangszertifikats-CA dieser Testseite. Nehmen Sie sie als Test-Vertrauensanker in Ihre Wallet auf, und Ihre Wallet kann jede hier registrierte Relying Party, jeden Aussteller und unseren eigenen Verifier prüfen. Diese Aufrufe brauchen keinen Schlüssel.

curl -s "https://phone.codeb.io/wrpac-ca.ashx?ca&format=pem" -o codeb-test-ca.pem
curl -s "https://phone.codeb.io/wrpac-ca.ashx?crl" -o codeb-test-ca.crl
curl -s "https://phone.codeb.io/playground.ashx?info"
AufrufLiefert
GET /wrpac-ca.ashx?caDas CA-Zertifikat (DER; &format=pem für PEM).
GET /wrpac-ca.ashx?crlDie Sperrliste für Zugangszertifikate. Widerrufen Sie eines Ihrer Zertifikate, und sie ändert sich sofort.
GET /wrpac-ca.ashx?rc-statusDie Statusliste für Registrierungszertifikate (die Adresse steht in der Angabe status jedes Zertifikats).
GET /wrpac-ca.ashx?registry=pg-…Der öffentliche Registereintrag einer Testorganisation.
GET /playground.ashx?infoAlle diese Adressen, den Fingerabdruck des CA-Zertifikats und die Limits als JSON. Für andere Origins offen (CORS).
{"name":"CodeB Playground","test":true,
 "ca":{"ca_url":"https://phone.codeb.io/wrpac-ca.ashx?ca","crl_url":"https://phone.codeb.io/wrpac-ca.ashx?crl",
       "rc_status_url":"...","registry_url":"https://phone.codeb.io/wrpac-ca.ashx?registry=",
       "subject":"...","sha256":"<fingerprint of the CA certificate>","not_after":"...","max_days":30,
       "sandbox":"playground"},
 "limits":{"organisations_per_account":2,"valid_certificates_per_organisation":5,"certificate_days":30}}

Vergleichen Sie den Fingerabdruck aus ?info mit dem Zertifikat, das Sie hinterlegen. So unterscheiden Sie Playground-Einträge von unseren eigenen: Playground-Zertifikate tragen die oben genannte Kennzeichnungs-Richtlinie und Einheit, ihre Registrierungszertifikate die Angabe codeb_playground. Dieser Anker gehört nicht in Produktions-Builds.

Weitere Aufrufe

AufrufKörperWirkung
GET /playground.ashxIhre Testorganisationen mit Zertifikaten und Vertrauensankern sowie die Limits.
POST ?op=revokeid, serialWiderruft eines Ihrer Zugangszertifikate.
POST ?op=deleteidEntfernt eine Testorganisation und widerruft ihre Zertifikate.
POST ?op=anchorid, kind, certificateAussteller: speichert das CA-Zertifikat, unter dem Ihr Testaussteller signiert (kind: mdoc-issuers oder vc-issuers), damit unser Verifier Ihre Attestierungen in einer Playground-Sitzung annimmt. Antwort: sha256.
POST ?op=anchor-removeid, kind, sha256Entfernt diesen Vertrauensanker.
curl -s "https://phone.codeb.io/playground.ashx" -H "Authorization: Bearer $PG_KEY"

curl -s "https://phone.codeb.io/playground.ashx?op=revoke" -H "Authorization: Bearer $PG_KEY" \
  -H "Content-Type: application/json" -d '{"id":"pg-3f9a1c0b7e","serial":"5d0c..."}'

curl -s "https://phone.codeb.io/playground.ashx?op=delete" -H "Authorization: Bearer $PG_KEY" \
  -H "Content-Type: application/json" -d '{"id":"pg-3f9a1c0b7e"}'

curl -s "https://phone.codeb.io/playground.ashx?op=anchor" -H "Authorization: Bearer $PG_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg c "$(cat my-test-root.pem)" '{id:"pg-3f9a1c0b7e", kind:"vc-issuers", certificate:$c}')"

Eine Playground-Sitzung unseres Verifiers beginnt mit /oidc.ashx?action=vp-start&sandbox=playground. Sie ist immer ein Test: Sie meldet nie an einem Konto an, und ihr Ergebnis sagt "test": true. Den Verifier selbst beschreibt die Wallet-API-Referenz.

Fehler und Limits

Ein Fehler ist ein JSON-Objekt mit error und, wo es hilft, error_description.

HTTPerrorBedeutung
400invalid_requestEin Feld fehlt oder wird nicht angenommen, oder die id ist keine Ihrer Testorganisationen. error_description nennt das Feld.
401unauthorizedKein Schlüssel, oder der Schlüssel ist unbekannt, widerrufen oder älter als 90 Tage, oder sein Konto existiert nicht mehr oder ist deaktiviert.
403sign_in_requiredSchlüssel werden auf der Playground-Seite verwaltet, nicht mit einem Schlüssel.
403account_without_emailDas Konto hat keine E-Mail-Adresse. Der Playground braucht eine.
404not_foundrevoke, delete, anchor-remove: Zertifikat, Organisation oder Vertrauensanker unbekannt oder nicht Ihre. Auch: Dieser Host hat keinen Playground.
409limit_reachedEin Limit des Playground ist erreicht. error_description nennt es.
409conflictIm Moment nicht möglich: Der Playground ist beschäftigt oder nicht eingerichtet, oder Vertrauensanker sind abgeschaltet. error_description nennt den Grund.
429rate_limitedZu viele Anfragen: höchstens 60 Änderungen pro Stunde je Konto und je Adresse und 600 Anfragen mit Schlüssel in 10 Minuten je Adresse.
503ca_key_unavailableDer Schlüsselspeicher der CA ist gerade nicht erreichbar. Bitte erneut versuchen.
LimitWert
Testorganisationen je Konto2
Neue Testorganisationen in 24 Stunden4 je Konto, 30 im gesamten Playground
Gültige Zugangszertifikate je Organisation5
Noch nicht abgelaufene Zugangszertifikate (widerrufene zählen bis zum Ablauf)10 je Organisation, 20 je Konto
Neue Zertifikate je Organisation in 24 Stunden10
Laufzeit eines Zugangszertifikats30 Tage
Laufzeit eines Registrierungszertifikats30 Tage
Registrierungszertifikate je Organisation pro Tag60
Credential-Abfragen in einer DCQL-Abfrage8
Attestierungstypen je Aussteller-Zertifikat16
Vertrauensanker je Organisation und Art2
API-Schlüssel je Konto3, 90 Tage gültig
Änderungen (POST) pro Stunde60 je Konto und 60 je Adresse
Anfragekörper64 KB

Eine Testorganisation, die 90 Tage nicht benutzt wurde, wird entfernt. Maschinenlesbare Beschreibung: openapi-playground.json (OpenAPI 3.1). Fragen: das Playground-Forum.