CodeB Playground · API

Playground API

Everything the playground page does, from a script or a build pipeline: register a test organisation, get an access certificate for your own key, get a registration certificate for what you ask for or issue, and fetch the one test trust anchor a wallet needs. JSON over HTTPS, four calls.

Test only. Certificates come from the CA of our test site, names carry the word TEST, nothing you send is verified and nothing is valid in production. Built to the EUDI Architecture and Reference Framework 3.0; our own assessment, nothing here is certified.

Authentication

Sign in on the playground page with your CodeB account and create an API key under “API keys”. The key is shown once. Send it with every call:

Authorization: Bearer pgk_...

01 · Register a test organisation

POST/playground.ashx?op=org

Creates a relying party, an issuer, or both in one entry. The answer carries the id (pg- and ten hex digits) you use in every later call.

FieldTypeRequiredMeaning
official_namestringyesOfficial name, at most 59 characters. Stored and shown as "TEST <name>".
org_idstringyesOrganisation identifier, a test value such as VATDE-123456789. 1 to 64 letters, digits, spaces and . / : + _ -
countrystringyesTwo-letter country code, for example DE.
rolesarrayyes"verifier" (relying party), "issuer", or both.
emailstringyesContact e-mail address. It goes into the certificate.
trade_namestringName shown to users.
entitlementsarrayIssuers only: Non_Q_EAA_Provider (default), PID_Provider, QEAA_Provider, PUB_EAA_Provider.
url, support_url, privacy_policy, info_uristringhttps addresses of your test service.
phone, services, intended_usestringOne line of text each.
idstringSend the id of an existing test organisation to change its contact data. Name, identifier and country cannot be changed.
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"}'

Answer

{"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":[]}]}

Not accepted: host names, addresses and e-mail domains of this site, and identifiers of its own entries. Texts are one line of visible characters.

02 · Get an access certificate for your own key

POST/playground.ashx?op=cert

You create the key and send a certificate request (PKCS#10, ECDSA P-256). The private key never leaves your machine. Only the public key of the request is used; the names in the certificate come from your test organisation.

openssl ecparam -name prime256v1 -genkey -noout -out verifier.key
openssl req -new -key verifier.key -subj "/CN=playground" -out verifier.csr
FieldTypeRequiredMeaning
idstringyesYour test organisation.
csrstringyesPKCS#10 request, PEM or base64 DER.
dnsarrayUp to 10 host names of your service, for x509_san_dns.
daysnumberLifetime, 1 to 30 (default 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}')"

Answer

{"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>"]}

The certificate follows the profile of ETSI TS 119 411-8. It carries the unit “CodeB Playground TEST” and the marker policy 2.25.195586870214937213748673734628273007303.99. x5c is ready for the header of your signed request.

03 · Get a registration certificate for what you ask for or issue

POST/playground.ashx?op=rc

Returns an rc-wrp+jwt per ETSI TS 119 475, valid 30 days, with a status reference. A relying party sends the DCQL query it presents to wallets; the certificate names exactly those credentials and claims.

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"]}]}]}}'

Issuer

An issuer lists the attestation types it issues: dc+sd-jwt with vct, or mso_mdoc with 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"}]}'

Answer

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

exp is a Unix time. The payload carries the private claim "codeb_playground": true, and its registry_uri leads to a public entry marked "test": true.

04 · Wallet builders: one test trust anchor for everything here

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

Every access certificate of the playground, and the certificate that signs its registration certificates, chain to one CA: the access-certificate CA of this test site. Add it to your wallet as a test trust anchor and your wallet can check every relying party and issuer registered here, and our own verifier. These calls need no key.

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"
CallReturns
GET /wrpac-ca.ashx?caThe CA certificate (DER; &format=pem for PEM).
GET /wrpac-ca.ashx?crlThe revocation list for access certificates. Revoke one of yours and it changes at once.
GET /wrpac-ca.ashx?rc-statusThe status list for registration certificates (the address is in each certificate’s status claim).
GET /wrpac-ca.ashx?registry=pg-…The public register entry of a test organisation.
GET /playground.ashx?infoAll of these addresses, the fingerprint of the CA certificate and the limits, as JSON. Open to other origins (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}}

Compare the fingerprint from ?info with the certificate you pin. To tell playground entries from our own: playground certificates carry the marker policy and the unit named above, and their registration certificates carry codeb_playground. Keep this anchor out of production builds.

More calls

CallBodyDoes
GET /playground.ashxYour test organisations with their certificates and trust anchors, and the limits.
POST ?op=revokeid, serialRevokes one of your access certificates.
POST ?op=deleteidRemoves a test organisation and revokes its certificates.
POST ?op=anchorid, kind, certificateIssuers: stores the CA certificate your test issuer signs under (kind: mdoc-issuers or vc-issuers), so our verifier accepts your attestations in a playground session. Answer: sha256.
POST ?op=anchor-removeid, kind, sha256Removes that trust anchor.
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}')"

A playground session of our verifier starts with /oidc.ashx?action=vp-start&sandbox=playground. It is always a test: it never signs in to an account, and its result says "test": true. The verifier itself is described in the wallet API reference.

Errors and limits

An error is a JSON object with error and, where it helps, error_description.

HTTPerrorMeaning
400invalid_requestA field is missing or not accepted, or the id is not one of your test organisations. error_description names the field.
401unauthorizedNo key, or the key is unknown, revoked or older than 90 days, or its account no longer exists or is disabled.
403sign_in_requiredKeys are managed on the playground page, not with a key.
403account_without_emailThe account has no e-mail address. The playground needs one.
404not_foundrevoke, delete, anchor-remove: unknown certificate, organisation or trust anchor, or not yours. Also: this host has no playground.
409limit_reachedA limit of the playground is reached. error_description says which one.
409conflictNot possible at the moment: the playground is busy or not set up, or trust anchors are switched off. error_description says why.
429rate_limitedToo many requests: at most 60 changes an hour per account and per address, and 600 requests with a key in 10 minutes per address.
503ca_key_unavailableThe key store of the CA is not reachable at the moment. Try again.
LimitValue
Test organisations per account2
New test organisations in 24 hours4 per account, 30 for the whole playground
Valid access certificates per organisation5
Access certificates that have not ended yet (revoked ones count until their end)10 per organisation, 20 per account
New certificates per organisation in 24 hours10
Lifetime of an access certificate30 days
Lifetime of a registration certificate30 days
Registration certificates per organisation a day60
Credential queries in one DCQL query8
Attestation types per issuer certificate16
Trust anchors per organisation and kind2
API keys per account3, valid 90 days
Changes (POST) per hour60 per account and 60 per address
Request body64 KB

A test organisation not used for 90 days is removed. Machine-readable description: openapi-playground.json (OpenAPI 3.1). Questions: the playground board.