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.
- Authentifizierung
- 01 Testorganisation
- 02 Zugangszertifikat
- 03 Registrierungszertifikat
- 04 Vertrauensanker
- Weitere Aufrufe
- Fehler und Limits
- OpenAPI 3.1
- Forum
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_...
- Ein Schlüssel steht für Ihr Konto im Playground und nirgends sonst. Er kann, was Sie auf der Playground-Seite können, außer Schlüssel erstellen oder widerrufen.
- 90 Tage gültig, 3 Schlüssel je Konto. Widerrufen Sie einen Schlüssel auf der Playground-Seite; er gilt sofort nicht mehr. Ein Schlüssel gilt auch nicht mehr, wenn sein Konto entfernt oder deaktiviert wird.
- Wir speichern einen Hash des Schlüssels, nicht den Schlüssel. Behandeln Sie ihn wie ein Passwort: im Secret-Speicher, nicht im Repository.
- Die Aufrufe 01 bis 03 sind
POSTmit JSON-Körper (Content-Type: application/json, UTF-8). Antworten sind JSON. Die Aufrufe aus Schritt 04 brauchen keinen Schlüssel.
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.
| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
official_name | string | ja | Offizieller Name, höchstens 59 Zeichen. Wird als "TEST <Name>" gespeichert und angezeigt. |
org_id | string | ja | Organisationskennung, ein Testwert wie VATDE-123456789. 1 bis 64 Buchstaben, Ziffern, Leerzeichen und . / : + _ - |
country | string | ja | Ländercode mit zwei Buchstaben, zum Beispiel DE. |
roles | array | ja | "verifier" (Relying Party), "issuer" oder beides. |
email | string | ja | Kontakt-E-Mail-Adresse. Sie steht im Zertifikat. |
trade_name | string | Name, der Nutzern angezeigt wird. | |
entitlements | array | Nur Aussteller: Non_Q_EAA_Provider (Standard), PID_Provider, QEAA_Provider, PUB_EAA_Provider. | |
url, support_url, privacy_policy, info_uri | string | https-Adressen Ihres Testdienstes. | |
phone, services, intended_use | string | Je eine Zeile Text. | |
id | string | Mit 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
| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
id | string | ja | Ihre Testorganisation. |
csr | string | ja | PKCS#10-Anforderung, PEM oder Base64-DER. |
dns | array | Bis zu 10 Hostnamen Ihres Dienstes, für x509_san_dns. | |
days | number | Laufzeit, 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"
| Aufruf | Liefert |
|---|---|
GET /wrpac-ca.ashx?ca | Das CA-Zertifikat (DER; &format=pem für PEM). |
GET /wrpac-ca.ashx?crl | Die Sperrliste für Zugangszertifikate. Widerrufen Sie eines Ihrer Zertifikate, und sie ändert sich sofort. |
GET /wrpac-ca.ashx?rc-status | Die 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?info | Alle 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
| Aufruf | Körper | Wirkung |
|---|---|---|
GET /playground.ashx | Ihre Testorganisationen mit Zertifikaten und Vertrauensankern sowie die Limits. | |
POST ?op=revoke | id, serial | Widerruft eines Ihrer Zugangszertifikate. |
POST ?op=delete | id | Entfernt eine Testorganisation und widerruft ihre Zertifikate. |
POST ?op=anchor | id, kind, certificate | Aussteller: 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-remove | id, kind, sha256 | Entfernt 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.
| HTTP | error | Bedeutung |
|---|---|---|
| 400 | invalid_request | Ein Feld fehlt oder wird nicht angenommen, oder die id ist keine Ihrer Testorganisationen. error_description nennt das Feld. |
| 401 | unauthorized | Kein Schlüssel, oder der Schlüssel ist unbekannt, widerrufen oder älter als 90 Tage, oder sein Konto existiert nicht mehr oder ist deaktiviert. |
| 403 | sign_in_required | Schlüssel werden auf der Playground-Seite verwaltet, nicht mit einem Schlüssel. |
| 403 | account_without_email | Das Konto hat keine E-Mail-Adresse. Der Playground braucht eine. |
| 404 | not_found | revoke, delete, anchor-remove: Zertifikat, Organisation oder Vertrauensanker unbekannt oder nicht Ihre. Auch: Dieser Host hat keinen Playground. |
| 409 | limit_reached | Ein Limit des Playground ist erreicht. error_description nennt es. |
| 409 | conflict | Im Moment nicht möglich: Der Playground ist beschäftigt oder nicht eingerichtet, oder Vertrauensanker sind abgeschaltet. error_description nennt den Grund. |
| 429 | rate_limited | Zu viele Anfragen: höchstens 60 Änderungen pro Stunde je Konto und je Adresse und 600 Anfragen mit Schlüssel in 10 Minuten je Adresse. |
| 503 | ca_key_unavailable | Der Schlüsselspeicher der CA ist gerade nicht erreichbar. Bitte erneut versuchen. |
| Limit | Wert |
|---|---|
| Testorganisationen je Konto | 2 |
| Neue Testorganisationen in 24 Stunden | 4 je Konto, 30 im gesamten Playground |
| Gültige Zugangszertifikate je Organisation | 5 |
| Noch nicht abgelaufene Zugangszertifikate (widerrufene zählen bis zum Ablauf) | 10 je Organisation, 20 je Konto |
| Neue Zertifikate je Organisation in 24 Stunden | 10 |
| Laufzeit eines Zugangszertifikats | 30 Tage |
| Laufzeit eines Registrierungszertifikats | 30 Tage |
| Registrierungszertifikate je Organisation pro Tag | 60 |
| Credential-Abfragen in einer DCQL-Abfrage | 8 |
| Attestierungstypen je Aussteller-Zertifikat | 16 |
| Vertrauensanker je Organisation und Art | 2 |
| API-Schlüssel je Konto | 3, 90 Tage gültig |
| Änderungen (POST) pro Stunde | 60 je Konto und 60 je Adresse |
| Anfragekörper | 64 KB |
Eine Testorganisation, die 90 Tage nicht benutzt wurde, wird entfernt. Maschinenlesbare Beschreibung: openapi-playground.json (OpenAPI 3.1). Fragen: das Playground-Forum.