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.
- Authentication
- 01 Test organisation
- 02 Access certificate
- 03 Registration certificate
- 04 Trust anchor
- More calls
- Errors and limits
- OpenAPI 3.1
- Discussion board
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_...
- A key stands for your account in the playground and nowhere else. It can do what you can do on the playground page, except create or revoke keys.
- Valid 90 days, 3 keys per account. Revoke a key on the playground page; it stops working at once. A key also stops working when its account is removed or disabled.
- We store a hash of the key, not the key. Keep it like a password: in a secret store, not in a repository.
- Calls 01 to 03 are
POSTwith a JSON body (Content-Type: application/json, UTF-8). Answers are JSON. The calls of step 04 need no key.
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.
| Field | Type | Required | Meaning |
|---|---|---|---|
official_name | string | yes | Official name, at most 59 characters. Stored and shown as "TEST <name>". |
org_id | string | yes | Organisation identifier, a test value such as VATDE-123456789. 1 to 64 letters, digits, spaces and . / : + _ - |
country | string | yes | Two-letter country code, for example DE. |
roles | array | yes | "verifier" (relying party), "issuer", or both. |
email | string | yes | Contact e-mail address. It goes into the certificate. |
trade_name | string | Name shown to users. | |
entitlements | array | Issuers only: Non_Q_EAA_Provider (default), PID_Provider, QEAA_Provider, PUB_EAA_Provider. | |
url, support_url, privacy_policy, info_uri | string | https addresses of your test service. | |
phone, services, intended_use | string | One line of text each. | |
id | string | Send 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
| Field | Type | Required | Meaning |
|---|---|---|---|
id | string | yes | Your test organisation. |
csr | string | yes | PKCS#10 request, PEM or base64 DER. |
dns | array | Up to 10 host names of your service, for x509_san_dns. | |
days | number | Lifetime, 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"
| Call | Returns |
|---|---|
GET /wrpac-ca.ashx?ca | The CA certificate (DER; &format=pem for PEM). |
GET /wrpac-ca.ashx?crl | The revocation list for access certificates. Revoke one of yours and it changes at once. |
GET /wrpac-ca.ashx?rc-status | The 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?info | All 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
| Call | Body | Does |
|---|---|---|
GET /playground.ashx | Your test organisations with their certificates and trust anchors, and the limits. | |
POST ?op=revoke | id, serial | Revokes one of your access certificates. |
POST ?op=delete | id | Removes a test organisation and revokes its certificates. |
POST ?op=anchor | id, kind, certificate | Issuers: 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-remove | id, kind, sha256 | Removes 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.
| HTTP | error | Meaning |
|---|---|---|
| 400 | invalid_request | A field is missing or not accepted, or the id is not one of your test organisations. error_description names the field. |
| 401 | unauthorized | No key, or the key is unknown, revoked or older than 90 days, or its account no longer exists or is disabled. |
| 403 | sign_in_required | Keys are managed on the playground page, not with a key. |
| 403 | account_without_email | The account has no e-mail address. The playground needs one. |
| 404 | not_found | revoke, delete, anchor-remove: unknown certificate, organisation or trust anchor, or not yours. Also: this host has no playground. |
| 409 | limit_reached | A limit of the playground is reached. error_description says which one. |
| 409 | conflict | Not possible at the moment: the playground is busy or not set up, or trust anchors are switched off. error_description says why. |
| 429 | rate_limited | Too many requests: at most 60 changes an hour per account and per address, and 600 requests with a key in 10 minutes per address. |
| 503 | ca_key_unavailable | The key store of the CA is not reachable at the moment. Try again. |
| Limit | Value |
|---|---|
| Test organisations per account | 2 |
| New test organisations in 24 hours | 4 per account, 30 for the whole playground |
| Valid access certificates per organisation | 5 |
| 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 hours | 10 |
| Lifetime of an access certificate | 30 days |
| Lifetime of a registration certificate | 30 days |
| Registration certificates per organisation a day | 60 |
| Credential queries in one DCQL query | 8 |
| Attestation types per issuer certificate | 16 |
| Trust anchors per organisation and kind | 2 |
| API keys per account | 3, valid 90 days |
| Changes (POST) per hour | 60 per account and 60 per address |
| Request body | 64 KB |
A test organisation not used for 90 days is removed. Machine-readable description: openapi-playground.json (OpenAPI 3.1). Questions: the playground board.