Sandbox: the test network
This guide is for anyone who wants to try software that connects to Tamga (above all a wallet, but also a verifier or an issuer) from start to finish without touching the real network.
When to read it:
- When you want to try receiving, presenting and revoking credentials in your wallet before a real institution issues any.
- When you want to see your verifier return the negative results correctly (revoked, suspended, a person under the age limit).
- After passing the [[GUIDE-0009|conformance tests]], when you test end to end with a real phone.
What is the sandbox?
The sandbox is Tamga Network's test network, fully separate from the real network (ADR-0038). The services run the same code as the real network; only the trust root, the keys, the trusted lists and the data are separate and fake:
- It has its own test root certificate: Tamga Sandbox Root CA (TEST). The real network's root signs nothing in the sandbox; the sandbox root appears in none of the real network's lists (
ADR-0038/SB1). - The sandbox LOTL (List of Trusted Lists)The signed list that points to the countries' trust lists, their signers and their recognition status. and its national list mark themselves as test with the field
"environment": "sandbox"(SPEC-TRUST-0001 §3). A wallet or verifier configured for the real network does not accept this list (ADR-0038/SB2). - People, events and credentials are examples; there is no real personal data. Identity verification uses a fake provider by default (
ADR-0038/SB3); anyone who wants can also try the real identity verification steps (§8, ADR-0040). The example institutions carry real institution names (see the note below). - Every sandbox page and every wallet screen connected to the sandbox shows a "SANDBOX · test" mark (
ADR-0038/SB4). - The data returns to its initial state every night (
ADR-0038/SB5).
A sandbox credential cannot be used in a real transaction: a real verifier does not recognise the sandbox root.
Addresses
The sandbox repeats the real network's address layout under the sandbox sub-name. A wallet or verifier switches by changing only the addresses and the trust anchor.
| Address | What | Real network counterpart |
|---|---|---|
https://sandbox.tamga.network | sandbox page: trust anchor, addresses, example people, credential offers, example verifiers | — |
https://trust.sandbox.tamga.network | test trusted lists (lotl.jws, tl-tr.jws), anchor log (anchors.jsonl), keys/ | trust.tamga.network |
https://issuer.sandbox.tamga.network/{institution} | issuance service of the example institutions (OpenID4VCI (OpenID for Verifiable Credential Issuance)The protocol an issuer uses to deliver a credential to a wallet.) | issuer.tamga.network |
https://status.sandbox.tamga.network | status lists (Token Status List) | status.tamga.network |
http(s)://crl.sandbox.tamga.network/<authority>.crl | revocation list of access certificates (RFC 5280 CRL; http and https, ADR-0090) | crl.tamga.network |
https://verify.sandbox.tamga.network | test verifier (OpenID4VP (OpenID for Verifiable Presentations)The protocol a verifier uses to request a credential from a wallet and receive the presentation.) | verify.tamga.network |
https://id.sandbox.tamga.network | identity and contact credentials; quick trial (made-up person) or verification with your real identity | id.tamga.network |
https://console.sandbox.tamga.network | Institution Console — only for test institutions opened in the sandbox | console.tamga.network |
The sandbox has no wallet provider of its own: the network runs no wallet provider, and wallet developers register their own provider in the sandbox list (§2, ADR-0042). The list has two special entries: TAMGA-SANDBOX-TEST-WP is a generic test key for the network's own trial scenes (not a real wallet; ADR-0042 K5); OIDF-CONFORMANCE-TEST is the test provider of the OpenID conformance tool (sandbox only). Tamga Wallet's provider (TAMGA-WP-1) is ACTIVE with the same entry and the same certificate in both the production and the sandbox list; there is no separate wallet sandbox.
Example institutions, people and permissions come from seed data and return to their initial state at every reset; the example institutions have no console. The Institution Console serves only the test institutions you open (§9, ADR-0041).
1. Pin the trust anchor
Wallets and verifiers accept the LOTL signature only with fingerprints built into the application; the list server is not trusted. Use a separate pin set for the sandbox:
- Take the SHA-256 fingerprints of the sandbox LOTL signer and the test root from
https://sandbox.tamga.network(the same values are inhttps://trust.sandbox.tamga.network/keys/root-fingerprints.json; compare them with the page). - Keep these fingerprints in a configuration separate from the real network's pins. Never merge the two sets.
- Pass the expected network when you load the list.
@tamga-network/trustand@tamga-network/wallet-coredo this with theenvironmentoption:
import { fetchTrustSource } from "@tamga-network/wallet-core";
const { source } = await fetchTrustSource("https://trust.sandbox.tamga.network", http, {
pins: { lotlSigners: [SANDBOX_LOTL_SIGNER_FINGERPRINT], environment: "sandbox" },
});If you write your own loader: after verifying the signature, compare the environment field of the LOTL and of the national list (absent means production); stop if it does not match (SPEC-TRUST-0001 §6).
2. Connect the wallet to the sandbox
There is a single sandbox and it belongs to the network: wallet developers use the same sandbox as institutions and verifiers; there is no separate wallet sandbox (ADR-0042). The network runs no wallet provider; in the sandbox too you run your own wallet provider.
Connect your wallet to the sandbox: follow the steps in GUIDE-0005 with the sandbox addresses:
| Setting | Sandbox value |
|---|---|
| trusted lists | https://trust.sandbox.tamga.network + sandbox pins + environment: "sandbox" |
| wallet provider (WIA / WUA) | the test address of your own wallet provider (must be registered in the sandbox list; see below) |
| identity credential service | https://id.sandbox.tamga.network |
| issuer directory | issuers[] in the sandbox national list (addresses on issuer.sandbox.tamga.network) |
Make the sandbox visible on screen (ADR-0038/SB4) and do not mix credentials received in the sandbox with real network credentials. You can switch between the real network and the sandbox with a developer setting you offer; keep the trust roots and credentials of the two networks apart. For example, in Tamga Wallet, the network's first wallet, the setting is under Settings → Developer → Network.
Register your wallet provider in the sandbox list
As on the real network, the sandbox issuers and identity service accept a wallet instance attestation (WIA) and key attestation (KA) only when they are signed by a wallet provider registered in the list. So before you try your wallet, your own provider must be registered under wallet_providers[] in the sandbox list:
- Generate a separate provider signing key for testing; do not use your real network key in the sandbox.
- Send your provider's address, its signing certificate and your wallet solution's name (
solution_id) to project management. Today registration is done by hand, with project management approval. - Once your entry is published in the sandbox list, try your wallet end to end with the sandbox's example institutions (§3), identity service (§5, §8) and example verifiers (§6).
Self-registration of wallet providers, and an automatic conformance test in which the sandbox tries the wallet at the address you give against the network's rules and reports back, are later stages and need their own decision. Until then, run the [[GUIDE-0009|conformance tests]] in your own environment.
3. Example institutions and credential types
About the institution names
The sandbox institutions exist only for testing; none of them implies a relationship or agreement with a real institution. The short names in the addresses (slug) are technical identifiers only. The credentials here are signed with a test key and are not valid anywhere. The institutions' logos are not used.
| Institution | Credential types (vct) |
|---|---|
Example university (TEST) — issuer.sandbox.tamga.network/example-university | urn:tamga:edu:StudentCredential:1, urn:tamga:edu:DiplomaCredential:1 |
Example events company (TEST) — issuer.sandbox.tamga.network/example-events | urn:tamga:tkt:EventTicket:1 (fictional concerts) |
Example cinema operator (TEST) — issuer.sandbox.tamga.network/example-cinema | urn:tamga:tkt:EventTicket:1 (fictional film screenings; a cinema ticket is not a separate type: the film and screening are in event_name, the hall in venue_name) |
Identity service — id.sandbox.tamga.network | urn:tamga:id:IdentityAttestation:1, pseudonym seed (PseudonymSeed), urn:tamga:contact:EmailAddress:1, urn:tamga:contact:PhoneNumber:1 |
4. Example people
The example people on the sandbox page are made up: 13 people from different countries, of different ages and in different situations. Their identity numbers have 12 digits and start with 99; they are deliberately invalid (ADR-0038/SB3). Some people are prepared for trying negative results:
| Person | Prepared state | Expected result |
|---|---|---|
| Timur Rahimov | the diploma is revoked right after issuance | REJECTED after the next status publication |
| Gülnaz Abenova | the diploma is suspended right after issuance | a suspended credential is not accepted; it can be reinstated from the offer page |
| Elvin Həsənov | the ticket is revoked right after issuance (refund) | the gate check returns REJECTED after the next status publication |
| Aibek Toktogulov | student with studies on hold (student_status: ON_LEAVE) | the student credential carries this state |
| Aruzhan Seitkali | 17 years old | the age check (≥ 18) fails |
| Deniz Örnek | no record at any institution | cannot get institution credentials |
A person's page (/people/<key>) shows the credentials that person can receive.
5. Get credentials
Institution credentials (student credential, diploma, ticket): on the person's page choose the credential type (for a ticket, the institution — concert or cinema —, the event and the ticket class). The page opens an OpenID4VCIThe protocol an issuer uses to deliver a credential to a wallet. offer: a QR code and a link (openid-credential-offer://…), plus a PIN (tx_code) shown separately. Scan the QR with the wallet and enter the PIN. The offer page shows when the credential has been issued and its state.
Identity and contact credentials: the wallet starts these (authorization code flow). The QR on the person's page is the identity service's offer. On the fake identity verification screen, choose the person named on the page; no real document or face scan is asked for.
Email and phone credentials: in the sandbox the code is not sent anywhere; it is shown in a "SANDBOX · TEST" box on the code entry screen. Only example addresses are accepted: an email at a .example or .test domain, or a phone number between +44 7700 900000 and +44 7700 900999 (the example people's addresses are on their pages). A real address is refused.
6. Present the credential
The example verifiers on the sandbox page open a signed OpenID4VPThe protocol a verifier uses to request a credential from a wallet and receive the presentation. request at the test verifier and show its QR. Scan it with the wallet; the result (ACCEPTED, REJECTED or INDETERMINATE), the checks performed and the shared fields appear on the same page.
Scenario (/verify/<scenario>) | What is requested |
|---|---|
signin | sign in with Tamga — pseudonym only |
signup | sign up to a site — given name, family name and pseudonym |
age | age ≥ 18 (selective disclosure) |
age-zk | age ≥ 18 with a zero-knowledge proof (if the wallet supports it) |
diploma | job application: diploma |
student | student discount: student credential |
ticket | event gate: ticket (concert or cinema) |
identity | event entry with the identity credential |
Gate (turnstile / ticket gate): https://verify.sandbox.tamga.network/terminal?group=<group> is the demo gate; it reads the pass QR from the wallet's “Show” screen with the camera. The gate identifies itself with a terminal key (ADR-0065); the sandbox's demo keys are public and go into the field on the page: example-university-campus → sandbox-gate-campus, example-events-gate → sandbox-gate-ticket. On the production network the gate's operator issues the key. In the sandbox list each gate group is bound to its institution (ADR-0069): example-university-campus → example-university, example-events-gate → example-events, example-cinema-gate → example-cinema; the admin of an institution with its own gates creates and revokes keys on the Gate terminals screen of the Institution Console (a key is shown once).
To try your own verifier: connect it to the sandbox list and the sandbox pins, then present credentials received in the sandbox. You can open your institution in the sandbox yourself (§9); today you register your wallet provider by request to project management (§2). Verifiers and wallet providers adding themselves to the sandbox list is a later stage.
From the browser (Digital Credentials API)
https://verify.sandbox.tamga.network/dc-api-test asks a wallet on the same device for a credential through the browser's Digital Credentials API (navigator.credentials.get({ digital: { requests } })) — no QR code. Choose what to ask for (over 18 as an mdoc, or a valid Tamga identity as an SD-JWT VC) and the protocol:
openid4vp-v1-signed— a signed OpenID4VPThe protocol a verifier uses to request a credential from a wallet and receive the presentation. request (OpenID4VP 1.0 Annex A):response_modedc_api.jwtandexpected_origins= the page's origin; the encrypted answer goes to/vp/response.org-iso-mdoc— ISO/IEC 18013-7 Annex C: aDeviceRequestwith reader authentication (the verifier's access certificate) and, when the verifier has one, its registration certificate inrequestInfo.euWrprc, plusEncryptionInfo; the wallet returns an HPKE-encryptedDeviceResponsebound to the page's origin (SessionTranscript with thedcapihandover), which goes to/vp/dc-mdoc/<id>. Only for a request for a single mdoc.- both — the browser and the wallet pick one.
The page's server opens the request at the verifier the way any relying party does (RP assertion), forwards nothing but the encrypted answer and shows the result: ACCEPTED or REJECTED, the checks performed, the verifier's trace and — sandbox sample data only — the disclosed values. A browser without the API gets a plain "not supported in this browser" message; the QR flow on the sample site (/sample-site) works everywhere. On a desktop, Chrome hands the request over to the phone.
7. Try revocation and suspension
The offer page of a diploma or a ticket has revoke, suspend and reinstate buttons. For the people with a prepared state (table above) this step happens by itself as soon as the credential is issued. The change takes effect when the issuer publishes its next status list (publication at a fixed interval; not instantly). Then present the same credential to an example verifier again: a revoked or suspended credential must not be accepted. The student credential is short-lived and carries no status list entry.
8. Try with your real identity
In the sandbox the identity flow offers two options (ADR-0040): Verify with your real identity — the remote identity verification provider's real steps (document scan, liveness, face match) — or Quick trial (made-up person) — you pick a made-up person and approve. The quick trial is open to everyone. Until the data-protection legal review is complete, the real path opens by default with an invitation code (ADR-0040/RI1, note of 2026-10-28); ask the sandbox team for one (support@tamga.network). Without a code use the quick trial.
- Connect the wallet to the sandbox and start adding an identity credential.
- On the identity service's page, accept the privacy notice, enter the invitation code and choose "Verify with your real identity".
- Read and confirm the warning: "This is a test environment; you are trying it with your real identity; your data is deleted every night; deletion of the verification session at the provider is requested as soon as the credential is issued." Without confirmation the provider is not opened (
ADR-0040/RI3). - Complete the steps on the provider's page; the test credential arrives in the wallet. The sandbox uses the real network's provider account; the keys that sign the credential and the records are separate (
ADR-0040/RI2).
Because the free verification allowance is shared with the real network, the real path has a daily and a monthly cap. When a cap is reached only the quick trial is shown ("Today's quota is full — use the quick trial"); each flow opens at most one real session (ADR-0040/RI7).
Only given name, family name and date of birth (and the derived age flag) go into the credential; instead of the real identity number and document number a random SANDBOX-… value is written (ADR-0040/RI4). Deletion of the verification session at the provider is requested as soon as the credential is issued or at once if verification fails, and for an abandoned session within about an hour, at the latest at the nightly reset (ADR-0040/RI5); the provider deletes within its own retention setting. Invitation codes are personal (single use, at most 7 days) or timed (at most 72 hours, at most 25 uses), cannot exceed the caps and are deleted at the nightly reset. After the legal review the sandbox administrator can switch the real path to the open mode.
9. Try your institution
An institution can try its own credential with its own (made-up) data in a few minutes (ADR-0041):
https://sandbox.tamga.network→ Try your institution. Enter a made-up institution name ("(TEST)" is added automatically) and choose the type (today an education institution: student credential and diploma). No email, phone or personal name is asked; real institution names and official-body words (T.C., Ministry, University …) are not accepted. Tick both boxes: made-up data only, deleted every night.- The institution is added to the sandbox trusted list at once, marked
test_institution: true. Its signing certificates are issued by the sandbox test institutions intermediate CA; credentials carry the leaf + intermediate chain and chain to the sandbox root (ADR-0041/TI1, SPEC-TRUST-0001 §4). - Create a passkey at
console.sandbox.tamga.networkwith the single-use invitation link on the page. - In the console: Records → enter records one by one or bulk-load them with Import CSV (first row: field names; at most 200 rows). A record containing an 11-digit number that passes the identity number checksum is rejected (
ADR-0041/TI4): use deliberately invalid numbers. - Next to a record: Issue at the desk → scan the QR with the wallet and enter the PIN.
- Present the credential at the "Diploma check" or "Student discount" verifier on the sandbox page.
Limits: at most 30 test institutions at a time (when full, the oldest empty test institution is removed to make room); at most 10 new institutions per 10 minutes; 200 records per institution; 100 offers per hour. The institution, its account, records and certificates are deleted every night and leave the sandbox list (ADR-0041/TI5). Event ticket institutions, wallet-initiated issuance and API keys for test institutions come in a later phase.
Your IT team reaches the same page with the onboarding tool: tamga-onboard sandbox prints the address and the steps, and tamga-onboard check --listing-only --env sandbox --slug t-… checks how the test institution appears in the sandbox list. For the institution's side of joining the real network (application file, keys and CSRs, setup check), see GUIDE-0014.
Rules and limits
- Do not enter real personal data. Only the example people, example addresses and made-up records go into the sandbox; the only exception is the real identity trial you choose yourself (§8), where only given name, family name and date of birth go into the credential.
- Do not expect persistence. Sandbox data returns to its initial state every night at 03:30 (Türkiye time): records of issued credentials, status lists and the anchor log are reset. Sandbox credentials in your wallet may no longer verify after a reset; get them again. The trust root and the list signing keys are not reset; the sandbox pins in the wallet do not change.
- Do not mix it with the real network. Do not add the sandbox pins to your real network configuration; a sandbox credential does not pass at a real verifier anyway.
- The sandbox has no service level commitment; its outages say nothing about the real network.
Related
ADR-0038 · ADR-0040 · ADR-0041 · ADR-0042 · SPEC-TRUST-0001 · GUIDE-0005 · GUIDE-0010 · GUIDE-0009 · GUIDE-0012 · GUIDE-0014