Test in the sandbox

The Phosra sandbox is an evaluation environment seeded with a demo family and synthetic reference providers. It exists so you can exercise a representative integration — connect a platform, set up a family, enforce a policy, sign a request — before you ever provision a key. This guide is the map: what is seeded, what is open, and how to get yourself onto the synthetic sandbox registry.

Response bodies below are examples of synthetic sandbox fixtures. Secret-bearing values are redacted.

The base URL

export SANDBOX="https://phosra-api-sandbox-production.up.railway.app"

What's already seeded

1. 1
   Confirm the sandbox is up

   The /health endpoint needs no key and is the fastest liveness check:

   bash

   curl -s "$SANDBOX/health"
   # → {"status":"ok"}

2. 2
   Read the signed Trust List

   The sandbox Trust List is a signed test artifact containing synthetic identities and tier fields. It is served at a well-known path and the entire document is Ed25519-signed by the sandbox root key. Verifying it demonstrates the mechanism; it does not prove accreditation.

   bash

   curl -s "$SANDBOX/.well-known/ocss/trust-list" \
     | jq '{alg, key_id, entries: (.document | fromjson | .entries | length)}'

   Real response (200):

   json

   {
     "alg": "ed25519",
     "key_id": "root-sandbox-2026-06",
     "entries": 135
   }

   The entries count is a live, growing number — every self-registration (below) adds an entry, so expect a value at or above the one shown here. Verify the signature and each entry's tier rather than asserting on the total.

   The top-level object wraps a signed document: { "document": "…", "key_id": "…", "alg": "ed25519", "sig": "…" }. Parse document (itself JSON) to read the entries array — each entry carries a did, an entity name, its published jwks signing keys, and a synthetic tier field. The @openchildsafety/ocss SDK verifies the signature and resolves keys for you.

   Fields & errors — GET /.well-known/ocss/trust-list

   No parameters, no auth. Returns the signed Trust List document.

   Top-level response fields (200)

   Field	Type	Description
   document	string	The Trust List as a JSON string — parse it to get { version, entries: [...] }. Signed as-is; verify before parsing.
   key_id	string	The signing key id, root-sandbox-2026-06 in the sandbox.
   alg	string	Signature algorithm, ed25519.
   sig	string	Base64url Ed25519 signature over document.

   Fields on each entry (inside the parsed document.entries)

   Field	Type	Description
   did	string	The party's DID.
   entity	string	Human-readable entity name.
   jwks	object	The party's published signing_keys (and payload_keys), for verifying its envelopes.
   tier	string	Sandbox fixture value: provisional, verified, or accredited; not an independent decision.
   status	string	active while the entry is valid.
   valid_through	string (RFC 3339)	When the entry expires.

3. 3
   Self-register a provisional DID

   You do not need anyone's approval to start testing signed flows. Post your DID and a raw Ed25519 public key (base64url, unpadded) to POST /api/v1/advisors/self-register, and the census adds you to the sandbox Trust List at the provisional tier.

   First, mint a keypair and extract the raw 32-byte public key:

   bash

   # Generate an Ed25519 private key
   openssl genpkey -algorithm ed25519 -out sandbox-key.pem
    
   # Extract the raw public key as base64url (unpadded)
   PUB=$(openssl pkey -in sandbox-key.pem -pubout -outform DER \
     | tail -c 32 | base64 | tr '+/' '-_' | tr -d '=')
   echo "$PUB"

   Then register:

   CodeCodeCodeCode

   bash
   curl -s -X POST "$SANDBOX/api/v1/advisors/self-register" \
     -H "Content-Type: application/json" \
     -d "{
       \"did\": \"did:ocss:dx-demo\",
       \"public_key_b64url\": \"$PUB\",
       \"roles\": [\"provider\"]
     }"

   Real response (200):

   json

   {
     "advisor_id": "fa97e1eb-1348-44c0-8954-2dec1df08d5c",
     "did": "did:ocss:dx-demo",
     "key_id": "did:ocss:dx-demo#2026-07",
     "kid": "2026-07",
     "published_key_x": "1NDtvUgkYV6h6XzR3y-FgAdKmqQ-i7XiWen7joyJYgA",
     "trust_tier": "provisional"
   }

   You are now on the sandbox Trust List. The key_id (did#kid) is what you sign your requests with; the census publishes your public key so counterparties can verify you.

   provisional is enough to test the signed flow in the sandbox. The other tier values are synthetic fixtures; no public production accreditation flow is claimed. See the design-partner and production roadmap.

   Fields & errors — POST /api/v1/advisors/self-register

   Request body (application/json)

   Field	Type	Required	Description
   did	string	yes	Your chosen DID, e.g. did:ocss:dx-demo.
   public_key_b64url	string	yes	Raw 32-byte Ed25519 public key, base64url, unpadded.
   roles	string[]	no	Roles to claim, e.g. ["provider"].
   key_id / kid	string	no	Optional key id; defaults to the current YYYY-MM (e.g. 2026-07).

   Response fields (200)

   Field	Type	Description
   advisor_id	string (UUID)	Your Trust List record id.
   did	string	Echoes your DID.
   key_id	string	Fully-qualified signing key id, did#kid.
   kid	string	The short key id, e.g. 2026-07.
   published_key_x	string	The public key the census published for you (base64url).
   trust_tier	string	provisional for a self-registration.

   Errors

   Status	message	When it happens
   400	did is required	did is missing from the body.
   400	public_key_b64url is required	The key field is missing.
   400	invalid_public_key_b64url: must decode to 32 bytes, got N	The key is not a valid 32-byte Ed25519 key (wrong length or bad encoding).

The sandbox host

Everything partner-facing points at one host — the same base URL used throughout these guides. It's open, seeded, and requires no key:

Now build something