> ## Documentation Index
> Fetch the complete documentation index at: https://docs.phosra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Example apps & starters

> A catalog of runnable, end-to-end sample integrations — a copy-paste starter that goes from zero to an enforced policy against the live sandbox, plus every real, published example repo and package you can clone today.

Everything on this page is **real and runnable today**. The starter below runs copy-paste against
the open sandbox with no API key; every repo and package in the catalog is published and linked to
its actual source — nothing here is a placeholder or a "coming soon."

<Info>
  **How to read this page.** We are explicit about what each sample *is*, because a dead link or a
  `404` on `npm install` costs a developer all their trust:

  * **Runnable starter** — a copy-paste snippet (not a repo) you can paste into a terminal right now.
    It runs against `https://phosra-api-sandbox-production.up.railway.app` with no credential. Every
    response shown is verbatim from that live sandbox.
  * **Clonable repo** — a public GitHub repository you can `git clone`. We link only repos that
    actually exist (verified against the GitHub API while writing this page).
  * **Published package** — on the public npm registry. Versions are verified against `npm view`;
    pin the one you use.
  * **Private / on-request** — the native iOS & Android enforcement SDKs are distributed privately.
    We say so plainly and give you the contact, rather than show an install line that would 404.
</Info>

## The 60-second starter

This is the smallest complete integration: **mint nothing, create a protected child, enforce the
policy, and read the result** — the same four moves every Phosra integration makes. It is a
**snippet, not a clonable repo**. It needs no API key because it targets the open sandbox.

<Steps>
  <Step title="Prove the sandbox is up" />

  <Step title="Create a family + child + active policy in one call" />

  <Step title="Enforce the policy (async job)" />

  <Step title="Poll the job to completion" />
</Steps>

<CodeGroup>
  ```bash cURL theme={null}
  # A complete, runnable integration — paste the whole block into a terminal.
  # No API key: this targets the open partner sandbox.
  HOST="https://phosra-api-sandbox-production.up.railway.app"
  BASE="$HOST/api/v1"

  # 1 — health check (no key)
  curl -s "$HOST/health"           # → {"status":"ok"}

  # 2 — create a protected child; capture the child id
  CHILD_ID=$(curl -s -X POST "$BASE/setup/quick" \
    -H "Content-Type: application/json" \
    -d '{"child_name":"Aria","birth_date":"2015-08-20","strictness":"recommended"}' \
    | jq -r '.child.id')
  echo "child: $CHILD_ID"

  # 3 — enforce → returns a job (status "running")
  JOB_ID=$(curl -s -X POST "$BASE/children/$CHILD_ID/enforce" | jq -r '.id')
  echo "job:   $JOB_ID"

  # 4 — poll the job until it is "completed"
  curl -s "$BASE/enforcement/jobs/$JOB_ID" | jq '{status, completed_at}'
  ```

  ```typescript TypeScript theme={null}
  // Full program. `npx tsx starter.ts` — Node 18+ (global fetch), zero dependencies.
  const BASE = "https://phosra-api-sandbox-production.up.railway.app/api/v1";

  async function main() {
    // 1 — health (no key)
    const health = await fetch(`${BASE.replace("/api/v1", "")}/health`).then((r) => r.json());
    console.log("health:", health.status); // ok

    // 2 — create family + child + active policy in one call
    const setup = await fetch(`${BASE}/setup/quick`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        child_name: "Aria",
        birth_date: "2015-08-20",
        strictness: "recommended",
      }),
    }).then((r) => r.json());
    const childId: string = setup.child.id;
    console.log("child:", childId, "| policy:", setup.policy.status, "| rules:", setup.rules.length);

    // 3 — enforce → async job
    const job = await fetch(`${BASE}/children/${childId}/enforce`, { method: "POST" }).then((r) =>
      r.json(),
    );
    console.log("job:", job.id, job.status);

    // 4 — poll until completed
    let result = job;
    while (result.status !== "completed" && result.status !== "failed") {
      await new Promise((r) => setTimeout(r, 500));
      result = await fetch(`${BASE}/enforcement/jobs/${job.id}`).then((r) => r.json());
    }
    console.log("final:", result.status, result.completed_at);
  }

  main();
  ```

  ```python Python theme={null}
  # Full program. `python starter.py` — needs `requests` (pip install requests).
  import time
  import requests

  BASE = "https://phosra-api-sandbox-production.up.railway.app/api/v1"

  # 1 — health (no key)
  print("health:", requests.get(f"{BASE.rsplit('/api/v1', 1)[0]}/health", timeout=30).json()["status"])

  # 2 — create family + child + active policy in one call
  setup = requests.post(
      f"{BASE}/setup/quick",
      json={"child_name": "Aria", "birth_date": "2015-08-20", "strictness": "recommended"},
      timeout=30,
  ).json()
  child_id = setup["child"]["id"]
  print("child:", child_id, "| policy:", setup["policy"]["status"], "| rules:", len(setup["rules"]))

  # 3 — enforce → async job
  job = requests.post(f"{BASE}/children/{child_id}/enforce", timeout=30).json()
  print("job:", job["id"], job["status"])

  # 4 — poll until completed
  while job["status"] not in ("completed", "failed"):
      time.sleep(0.5)
      job = requests.get(f"{BASE}/enforcement/jobs/{job['id']}", timeout=30).json()
  print("final:", job["status"], job["completed_at"])
  ```

  ```go Go theme={null}
  // Full program. Save as main.go in an empty dir, then `go mod init starter && go run .`
  package main

  import (
  	"bytes"
  	"encoding/json"
  	"fmt"
  	"net/http"
  	"time"
  )

  const base = "https://phosra-api-sandbox-production.up.railway.app/api/v1"

  type job struct {
  	ID          string `json:"id"`
  	Status      string `json:"status"`
  	CompletedAt string `json:"completed_at"`
  }

  func main() {
  	// 2 — create family + child + active policy in one call
  	body, _ := json.Marshal(map[string]string{
  		"child_name": "Aria", "birth_date": "2015-08-20", "strictness": "recommended",
  	})
  	res, _ := http.Post(base+"/setup/quick", "application/json", bytes.NewReader(body))
  	var setup struct {
  		Child struct {
  			ID string `json:"id"`
  		} `json:"child"`
  		Policy struct {
  			Status string `json:"status"`
  		} `json:"policy"`
  		Rules []json.RawMessage `json:"rules"`
  	}
  	json.NewDecoder(res.Body).Decode(&setup)
  	res.Body.Close()
  	fmt.Println("child:", setup.Child.ID, "| policy:", setup.Policy.Status, "| rules:", len(setup.Rules))

  	// 3 — enforce → async job
  	res, _ = http.Post(base+"/children/"+setup.Child.ID+"/enforce", "application/json", nil)
  	var j job
  	json.NewDecoder(res.Body).Decode(&j)
  	res.Body.Close()
  	fmt.Println("job:", j.ID, j.Status)

  	// 4 — poll until completed
  	for j.Status != "completed" && j.Status != "failed" {
  		time.Sleep(500 * time.Millisecond)
  		res, _ = http.Get(base + "/enforcement/jobs/" + j.ID)
  		json.NewDecoder(res.Body).Decode(&j)
  		res.Body.Close()
  	}
  	fmt.Println("final:", j.Status, j.CompletedAt)
  }
  ```
</CodeGroup>

**Verbatim sandbox output** (captured while writing this page — `setup/quick` returns `200`, the
enforce job flips to `completed` in well under a second):

```jsonc theme={null}
// POST /setup/quick — trimmed to the fields the starter reads
{
  "family": { "id": "ecf280b3-b684-4945-a694-18a4f566a450", "name": "Aria's Family" },
  "child":  { "id": "ef0ca46d-411e-4801-9a5d-a05dd599c093", "name": "Aria",
              "birth_date": "2015-08-20T00:00:00Z" },
  "policy": { "id": "fe8203da-00d5-45b9-bfa9-76f3f3227bdd",
              "name": "Aria's Protection Policy", "status": "active" },
  "rules":  [ /* 20 age-appropriate rules, enabled */ ]
}

// POST /children/{id}/enforce — the async job, immediately after the call
{ "id": "0eb048ce-497c-4193-ba32-5dc9a0894954", "status": "running", "trigger_type": "manual" }

// GET /enforcement/jobs/{id} — after polling
{ "id": "0eb048ce-497c-4193-ba32-5dc9a0894954", "status": "completed",
  "completed_at": "2026-07-06T11:22:04.645214Z" }
```

<Tip>
  **Add the webhook leg.** The starter stops at "enforce + read result." To finish a production-grade
  integration, register a webhook so your backend is *pushed* the change instead of polling. That step
  needs a `phosra_test_` key (webhook registration is authenticated). The **verified, copy-paste
  signature-verifying handler** — in curl, TypeScript, Python, and Go — lives in
  [Webhook events → Verifying signatures](/guides/webhook-events#verifying-signatures).
</Tip>

## What the starter builds, in a real app

The four API calls above are exactly what a parental-control app runs behind its UI. Every screen
below is a **real screenshot** captured from Propagate — a reference app built on this same sandbox
API — following one child (Ruby) end to end. Nothing is mocked or drawn.

<Frame caption="setup/quick, rendered for a human: a family with a child and a starter policy. The same call the starter's step 2 makes.">
  <img src="https://mintcdn.com/phosra/o0ansqUg4hqAQihW/images/walkthrough/ff-01-family.jpg?fit=max&auto=format&n=o0ansqUg4hqAQihW&q=85&s=03dd7172a65a27b93e20f23975638d7c" alt="Propagate iOS Family screen listing children Ruby and Mateo under a KIDS section, with the parent shown as Owner under a PARENTS section, and a bottom tab bar." width="1206" height="2622" data-path="images/walkthrough/ff-01-family.jpg" />
</Frame>

<Frame caption="The link ceremony — the app-side equivalent of pushing a policy to a platform. It states, up front, exactly which rules the platform will apply and confirm before anything turns green.">
  <img src="https://mintcdn.com/phosra/o0ansqUg4hqAQihW/images/walkthrough/ff-03-link-ceremony.jpg?fit=max&auto=format&n=o0ansqUg4hqAQihW&q=85&s=a86c89e79ccaacfbc943c93d36d0be29" alt="Propagate 'Connect Notflix' screen under a 'phosra · OCSS' header, listing four rules the platform will apply and verify, with a green Continue button and an honesty disclaimer." width="1206" height="2622" data-path="images/walkthrough/ff-03-link-ceremony.jpg" />
</Frame>

<Frame caption="Enforced and confirmed — the human-readable form of a verified compliance link: 'Applied & verified just now', with the applied rules listed underneath.">
  <img src="https://mintcdn.com/phosra/o0ansqUg4hqAQihW/images/walkthrough/ff-04-linked.jpg?fit=max&auto=format&n=o0ansqUg4hqAQihW&q=85&s=79dad33a3fdd6281be605af04d2c8f83" alt="Propagate platform detail screen with a green shield 'Enforced' card, a Status section (Protection type Enforced, Connected date, Last sync 'Applied & verified just now'), and an Applied Rules list with green checkmarks." width="1206" height="2622" data-path="images/walkthrough/ff-04-linked.jpg" />
</Frame>

<Note>
  Want the full ten-phase lifecycle — link, unlink, per-service isolation, relink — with every request
  and response run live? See the [End-to-end walkthrough](/guides/end-to-end-walkthrough).
</Note>

## The catalog

Real, published integrations you can clone or install today. The two GitHub repositories below are
public in the [`Phosra-Inc` org](https://github.com/orgs/Phosra-Inc/repositories):

<Frame caption="The public Phosra-Inc GitHub organization — the two example repositories in the catalog below are real and clonable. Captured from github.com.">
  <img src="https://mintcdn.com/phosra/o0ansqUg4hqAQihW/images/example-apps-github-repos.jpg?fit=max&auto=format&n=o0ansqUg4hqAQihW&q=85&s=7bf88fd9a0afeb79d15deab6d8fda718" alt="GitHub organization page for Phosra-Inc showing two public repositories: 'touchstone' (TypeScript, MIT License) and 'phosra-link-kit-ios' (Swift), each marked Public." width="1280" height="900" data-path="images/example-apps-github-repos.jpg" />
</Frame>

### Clonable repos

<CardGroup cols={2}>
  <Card title="Provider conformance harness" icon="github" href="https://github.com/Phosra-Inc/touchstone">
    **`Phosra-Inc/touchstone`** (TypeScript, MIT). The independent OCSS conformance harness — probe a
    provider enclave and print a signed report. Zero runtime dependencies.

    ```bash theme={null}
    npm install @openchildsafety/provider-harness
    npx ocss-harness run --enclave ref
    ```
  </Card>

  <Card title="iOS Link kit (Connect sheet)" icon="apple" href="https://github.com/Phosra-Inc/phosra-link-kit-ios">
    **`Phosra-Inc/phosra-link-kit-ios`** (Swift). The native-iOS Phosra Link — a branded Connect sheet
    your app presents in \~10 lines, with `onSuccess` / `onExit` callbacks. The Plaid-LinkKit analog.

    ```swift theme={null}
    .package(url: "https://github.com/Phosra-Inc/phosra-link-kit-ios.git", from: "0.1.0")
    ```
  </Card>
</CardGroup>

### Run without cloning — one-command samples

Each of these runs a real integration from a single command against the sandbox.

<CardGroup cols={2}>
  <Card title="MCP server for AI agents" icon="robot" href="/sdks/mcp-server">
    Expose Phosra tools to Claude, GPT, and any MCP client. One command, no clone:

    ```bash theme={null}
    npx @phosra/mcp --api-key=YOUR_KEY
    ```

    Full client config (Claude Desktop, Cursor) on the [MCP Server](/sdks/mcp-server) page.
  </Card>

  <Card title="Partner CLI — sandbox round-trip" icon="terminal" href="/integration/cli">
    Scaffold configs and run a sandbox round-trip check without writing code:

    ```bash theme={null}
    npx @phosra/cli doctor
    ```

    See the [CLI guide](/integration/cli) for every subcommand.
  </Card>

  <Card title="Embeddable Connect component" icon="plug" href="/sdks/link">
    The "Plaid Link" for parental-controls apps — web + React Native. Drives the consent ceremony end
    to end:

    ```bash theme={null}
    npm install @phosra/connect
    ```
  </Card>

  <Card title="OCSS protocol reference lib" icon="cube" href="/sdks/phosra-developer-sdk">
    Sign/verify receipts, sealed envelopes, the Trust List — the vendor-neutral OCSS surface, no
    Phosra account:

    ```bash theme={null}
    npm install @openchildsafety/ocss
    ```
  </Card>
</CardGroup>

### Every published package

All verified against the public npm registry while writing this page — pin the version you use.

| Package                                                                                                | Version | Sample it powers                                              | Docs                                        |
| ------------------------------------------------------------------------------------------------------ | ------- | ------------------------------------------------------------- | ------------------------------------------- |
| [`@phosra/sdk`](https://www.npmjs.com/package/@phosra/sdk)                                             | `0.1.0` | Typed control-plane client — the 60-second starter, but typed | [TypeScript SDK](/sdks/typescript)          |
| [`@phosra/mcp`](https://www.npmjs.com/package/@phosra/mcp)                                             | `0.4.0` | MCP server for AI agents (`npx @phosra/mcp`)                  | [MCP Server](/sdks/mcp-server)              |
| [`@phosra/cli`](https://www.npmjs.com/package/@phosra/cli)                                             | `0.2.0` | Sandbox round-trip + scaffolding (`npx @phosra/cli`)          | [CLI](/integration/cli)                     |
| [`@phosra/link`](https://www.npmjs.com/package/@phosra/link)                                           | `0.1.2` | The consent ceremony + signed rule-write directives           | [Link](/sdks/link)                          |
| [`@phosra/connect`](https://www.npmjs.com/package/@phosra/connect)                                     | `0.1.1` | Embeddable Connect component (web + React Native)             | [Link](/sdks/link)                          |
| [`@phosra/gatekeeper`](https://www.npmjs.com/package/@phosra/gatekeeper)                               | `0.2.2` | Platform-side: verify signed profiles, local decision engine  | [Platform](/integration/platform)           |
| [`@openchildsafety/ocss`](https://www.npmjs.com/package/@openchildsafety/ocss)                         | `0.1.3` | The OCSS reference library (receipts, envelopes, trust list)  | [Developer SDK](/sdks/phosra-developer-sdk) |
| [`@openchildsafety/provider-harness`](https://www.npmjs.com/package/@openchildsafety/provider-harness) | `0.1.3` | The `touchstone` conformance harness above                    | [Provider](/integration/provider)           |

<Note>
  **No `@ocss/*` scope exists.** The open standard's library ships under **`@openchildsafety/*`**, and
  the Phosra client libraries under **`@phosra/*`**. If you see an `@ocss/…` install line anywhere, it
  is wrong — it will 404 on npm.
</Note>

### Private / on-request

The native on-device enforcement SDKs are **not on a public registry yet** — we distribute them
privately rather than show an install line that would fail.

| SDK                     | Status                         | How to get it                                                |
| ----------------------- | ------------------------------ | ------------------------------------------------------------ |
| iOS enforcement SDK     | Private repo                   | [iOS SDK](/sdks/ios) · email `developers@phosra.com`         |
| Android enforcement SDK | Private (not on Maven Central) | [Android SDK](/sdks/android) · email `developers@phosra.com` |

<Info>
  The iOS **Link kit** ([`phosra-link-kit-ios`](https://github.com/Phosra-Inc/phosra-link-kit-ios)) —
  the Connect *sheet* — is public and in the catalog above. The separate iOS **enforcement** SDK (the
  one that drives FamilyControls / ManagedSettings on-device) is the private one.
</Info>

## Reference provider integrations

The sandbox ships a **built-in reference provider** that powers the live OAuth consent page you meet
in the [Connect a platform](/guides/connect-a-platform) guide and the
[end-to-end walkthrough](/guides/end-to-end-walkthrough). It exposes real `/oauth/authorize`,
`/oauth/token`, and `/oauth/profiles` endpoints with fixed demo child profiles (Mia, Leo, Ava), so
you can drive a complete connect ceremony against the sandbox without standing up your own provider.

<Warning>
  The brand names in the walkthrough screenshots — "Notflix", "Pixagram" — are the reference app's
  **stand-in labels**, not separate clonable projects or accredited providers. There is no public
  "Notflix" repository; the sandbox's reference OAuth surface is what makes that flow runnable. We call
  this out so you don't go looking for a repo that doesn't exist.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    The same first calls, with more explanation of each field and response.
  </Card>

  <Card title="End-to-end walkthrough" icon="route" href="/guides/end-to-end-walkthrough">
    The full family lifecycle — link, unlink, isolation, relink — run live.
  </Card>

  <Card title="Webhook events" icon="bell" href="/guides/webhook-events">
    Finish the starter: verified signature-checking handlers in four languages.
  </Card>

  <Card title="Get your API key" icon="key" href="/platform/create-account">
    Move from the sandbox to production — same request shapes, one new header.
  </Card>
</CardGroup>