Skip to main content
A platform (also called a provider) is anything Phosra can push a child-safety policy to — a DNS filter, a router, an app, an operating system. Before Phosra can enforce anything, a parent has to connect the platform and approve sharing their children’s profiles. This guide walks the full connect ceremony — discovery → consent → token → profiles — against the public sandbox. Every request and response below is verbatim live output, captured while writing this page. No API key, nothing to install. The four calls chain end to end: discover the endpoints (GET /providers/{did}/connect) → send the parent to consent (authorize_url) → exchange the returned code for a token (token_url) → read the approved profiles (profiles_url). Each step below carries a Fields & errors reference you can expand.
Sandbox-first. The reference provider used here — did:ocss:loopline — is seeded into the partner sandbox at https://phosra-api-sandbox-production.up.railway.app. Nothing you connect there touches a real family. The endpoint shapes are identical in production; you swap the base URL for https://prodapi.phosra.com and connect a real provider DID.

Before you start

Set the base URL once so every step is copy-paste:
You will connect the sandbox’s reference provider, Loopline (did:ocss:loopline). It is a real, accredited entry on the sandbox Trust List with a live OAuth surface — the same shape a production provider exposes.
1

Discover the provider's connect endpoints

Every connectable provider publishes its OAuth endpoints at GET /providers/{did}/connect. Start there — never hard-code the URLs.
Real response (200):
A provider that is accredited but has not configured a connect surface returns 404 provider connect config not available. In the sandbox, did:ocss:courier is deliberately left unconfigured so you can test that branch.
Path parameterResponse fields (200)Errors
2

Send the parent to the consent page

Redirect the parent’s browser to authorize_url with your client_id (the provider DID), a redirect_uri, and an opaque state you generate:
The sandbox serves a real consent screen. The parent sees exactly which child profiles they are about to share, and chooses Approve or Deny:
Phosra sandbox consent page titled 'Connect your family to this app?' listing Mia, Leo, and Ava as child profiles, with Approve and Deny buttons

The live sandbox consent page for did:ocss:loopline — captured from the running server, not a mockup.

This consent page is a sandbox demo, not a production IdP. The census’s reference authorize surface auto-approves the seeded test family (Mia/Leo/Ava) with no login — a sandbox affordance, gated to PHOSRA_ENV=sandbox (it returns 404 on the production census by design). In production, the provider redirects to the platform’s own authorize_url, and the platform hosts this page. The platform authenticates its real account holder (a genuine login or existing session) before consent, and returns that account’s real child profiles to the token/profiles exchange — never a seeded identity. The census never hosts a production consent IdP; the platform authenticates its own users (EXT-04 §3.2 step 3). So when you go live, authorize_url points at your platform, not here.
Query parametersOutcomesErrors
3

Receive the authorization code

On Approve, Phosra redirects back to your redirect_uri with a short-lived code and the state you sent (verify it matches before continuing):
On Deny, no code is issued — you get ?error=access_denied&state=… instead. Handle both. See Disconnect & reconnect for the decline path in full.
Query parameters Phosra appends to your redirect_uri
4

Exchange the code for an access token

Trade the code for a bearer token at token_url:
Real response (200):
On the scope value. Discovery advertises the requested scope as child_profiles.read (the canonical name), while the issued token echoes the short form scope: "profiles". Both name the same grant — read-only access to the approved children. Key your logic off the token you were issued, not off a hard-coded string, and treat the two as equivalent.
Request body (application/json)Response fields (200)Errors
Sandbox stub behaviour. The sandbox /oauth/token surface is a stateless reference stub: it does not persist or validate the code, so an expired or reused code still returns a token in the sandbox. In production, a provider’s real token endpoint returns 400 invalid_grant for an expired, reused, or unknown code — write your error handling for that before you go live.
5

Read the shared child profiles

Call profiles_url with the token. You get back exactly the children the parent approved — each with a stable subject_ref you use for policy and enforcement calls:
Real response (200):
The platform is now connected. Hold onto each subject_ref — that is the handle you pass to the policy and enforcement endpoints in Set up a family & kids.
Request headerResponse fields (200) — an array, one object per approved childErrors
Sandbox stub behaviour. Because the sandbox surface is stateless, any non-empty Bearer value returns the seeded profiles — only a missing header yields 401. A production provider validates the token and returns 401 invalid_token for any expired or forged token, so treat 401 as “re-run the connect ceremony” in your client.

Which platform supports which rule?

Not every platform can enforce every rule. Discovery endpoints let you pick the right one before you ask a parent to connect:
Check each platform’s enforcement_mode: dns, device, and oauth2 platforms are applied programmatically, while manual_attested platforms require the parent to complete a guided step by hand. See Platforms & enforcement modes.

Production notes

In production, connecting an account-linked platform (one where you hold a per-family credential rather than an OAuth grant) uses POST /compliance with your phosra_live_… key — see First-time setup. Those endpoints are family-scoped and require an authenticated caller who is a member of the family, so they cannot be exercised anonymously against the open sandbox. The OAuth ceremony above is the anonymous, fully runnable path.

Next steps

Set up a family & kids

Build a family, add children, and get an age-appropriate policy in one call.

Disconnect & reconnect

Handle the decline path, tear a link down, and re-approve cleanly.