First-Time Setup

This guide covers integrating Phosra into your application from scratch, including API key provisioning and your first enforcement run.

One auth header, everywhere. Every raw HTTP call on this page sends your key as Authorization: Bearer $PHOSRA_API_KEY — the one canonical form (X-Api-Key is accepted as an exact equivalent, but we use Bearer consistently so keys, WorkOS JWTs, and MCP tokens all share one header). Full detail: Authentication.

1. Create Your Account

Sign up at dashboard.phosra.com/signup via the WorkOS AuthKit hosted sign-up flow. There is no /auth/register endpoint on the Go API — account creation is handled by WorkOS. Once signed in, continue to step 2. (Full walkthrough: Create your account & get keys.)

2. Get an API Key

Use the developer console’s Keys page or call the API with your WorkOS session:

curl -X POST https://prodapi.phosra.com/api/v1/developers/orgs \
  -H "Authorization: Bearer <workos_access_token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Integration"}'

# Then create a key for the org:
curl -X POST https://prodapi.phosra.com/api/v1/developers/orgs/{orgId}/keys \
  -H "Authorization: Bearer <workos_access_token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "server-key", "scopes": ["read:families","write:policies","write:enforcement"]}'

The response includes the key once. Store it immediately:

# Production key
export PHOSRA_API_KEY="phosra_live_4a1b2c..."

# Sandbox key (use against https://phosra-api-sandbox-production.up.railway.app/api/v1)
export PHOSRA_API_KEY="phosra_test_4a1b2c..."

Key format: phosra_live_<64 hex chars> (production) or phosra_test_<64 hex chars> (sandbox). There is no _sk_ infix.

3. Use Quick Setup for Onboarding

The fastest path for your end users. When a parent signs up and adds their first child in your app, call the quick setup endpoint — as the signed-in parent, not with your phosra_ key. /setup/quick is a consumer route: in production it authenticates a WorkOS session JWT (Authorization: Bearer <workos_access_token>) belonging to that parent, and a phosra_ key sent instead returns 401. There is no /developer/setup/quick — a server-to-server integration that must act without a parent session builds the same graph from /developer/families, /developer/children, and /developer/policies instead (each of those does accept $PHOSRA_API_KEY).

curl -X POST https://prodapi.phosra.com/api/v1/setup/quick \
  -H "Authorization: Bearer $WORKOS_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "child_name": "Emma",
    "birth_date": "2016-03-15",
    "strictness": "recommended"
  }'

// Called from your backend, forwarding the parent's WorkOS access token — not a phosra_ key.
const res = await fetch("https://prodapi.phosra.com/api/v1/setup/quick", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${workosAccessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    child_name: "Emma",
    birth_date: "2016-03-15",
    strictness: "recommended",
  }),
});
const setup = await res.json();
// setup.family.id, setup.child.id — store both

import requests

r = requests.post(
    "https://prodapi.phosra.com/api/v1/setup/quick",
    headers={"Authorization": f"Bearer {workos_access_token}"},
    json={"child_name": "Emma", "birth_date": "2016-03-15", "strictness": "recommended"},
    timeout=30,
)
r.raise_for_status()
setup = r.json()
family_id, child_id = setup["family"]["id"], setup["child"]["id"]

package main

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

func main() {
	payload, _ := json.Marshal(map[string]string{
		"child_name": "Emma", "birth_date": "2016-03-15", "strictness": "recommended",
	})
	req, _ := http.NewRequest("POST",
		"https://prodapi.phosra.com/api/v1/setup/quick", bytes.NewReader(payload))
	req.Header.Set("Authorization", "Bearer "+workosAccessToken)
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var setup struct {
		Family struct{ ID, Name string } `json:"family"`
		Child  struct{ ID, Name string } `json:"child"`
	}
	json.NewDecoder(resp.Body).Decode(&setup)
	fmt.Println(setup.Family.ID, setup.Child.ID) // store both for step 6
}

This returns a family, child, and an active policy with age-appropriate rules populated across the applicable rule categories for the requested strictness level, plus age_group, max_ratings, and rule_summary. Store the family.id and child.id for subsequent calls.

Prefer to try this without any auth first? The Quickstart runs the exact same call against the open sandbox — no credential at all — and shows the real response. In the sandbox /setup/quick is keyless; the WorkOS session requirement above applies to production only.

4. Connect Platforms

For each platform the family uses, create a compliance link:

curl -X POST https://prodapi.phosra.com/api/v1/compliance \
  -H "Authorization: Bearer $PHOSRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "family_id": "FAMILY_UUID",
    "platform_id": "nextdns",
    "credentials": "nextdns-api-key"
  }'

List available platforms with GET /platforms to see what integrations are supported, and check each platform’s enforcement_mode — one of dns, device, or manual_attested. dns and device apply rules programmatically (a live DNS-provider write, or on-device via the Phosra app); manual_attested returns guided steps for the parent to attest. See Platforms & enforcement modes.

5. Register Webhooks

Set up webhooks to receive real-time event notifications when a child’s policy changes (the full event catalog is exactly five events — policy.updated, pack.adopted, pack.revoked, pack.version.released, test; see Webhook events):

curl -X POST https://prodapi.phosra.com/api/v1/webhooks \
  -H "Authorization: Bearer $PHOSRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "family_id": "FAMILY_UUID",
    "url": "https://yourapp.com/webhooks/phosra",
    "events": ["policy.updated"]
  }'

Note: webhooks do not fire on enforcement job completion. To verify enforcement results, poll GET /enforcement/jobs/{jobId}/results — see Enforcement.

6. Trigger Enforcement

Push the policy to all connected platforms, then poll the returned job for results:

BASE="https://prodapi.phosra.com/api/v1"
CHILD_ID="CHILD_UUID"   # from setup.child.id in step 3

# Trigger — returns a job (202 Accepted)
JOB_ID=$(curl -s -X POST "$BASE/children/$CHILD_ID/enforce" \
  -H "Authorization: Bearer $PHOSRA_API_KEY" | jq -r .id)

# Poll results
curl -s "$BASE/enforcement/jobs/$JOB_ID/results" \
  -H "Authorization: Bearer $PHOSRA_API_KEY"

import { PhosraClient } from "@phosra/sdk";

const phosra = new PhosraClient({ apiKey: process.env.PHOSRA_API_KEY });
const childId = "CHILD_UUID"; // from setup.child.id in step 3

const job = await phosra.enforcement.trigger(childId);
// poll until done
const results = await phosra.enforcement.getResults(job.id);
console.log(results);

import os, requests

BASE = "https://prodapi.phosra.com/api/v1"
child_id = "CHILD_UUID"  # from setup["child"]["id"] in step 3

session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['PHOSRA_API_KEY']}"

job = session.post(f"{BASE}/children/{child_id}/enforce", timeout=30).json()
results = session.get(f"{BASE}/enforcement/jobs/{job['id']}/results", timeout=30).json()
print(results)

package main

import (
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	base := "https://prodapi.phosra.com/api/v1"
	childID := "CHILD_UUID" // from setup.Child.ID in step 3
	key := os.Getenv("PHOSRA_API_KEY")

	// Trigger enforcement — returns a job.
	req, _ := http.NewRequest("POST", base+"/children/"+childID+"/enforce", nil)
	req.Header.Set("Authorization", "Bearer "+key)
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	var job struct {
		ID string `json:"id"`
	}
	json.NewDecoder(resp.Body).Decode(&job)
	resp.Body.Close()

	// Poll results.
	rreq, _ := http.NewRequest("GET",
		base+"/enforcement/jobs/"+job.ID+"/results", nil)
	rreq.Header.Set("Authorization", "Bearer "+key)
	rresp, err := http.DefaultClient.Do(rreq)
	if err != nil {
		panic(err)
	}
	defer rresp.Body.Close()
	body, _ := io.ReadAll(rresp.Body)
	fmt.Printf("%s\n", body)
}

A non-empty manual_steps array on any result means that platform is parent-guided, not programmatically applied.

Handle errors

Every failure returns a JSON envelope of the shape {"error", "message", "code"} (OCSS routes add class and, on standing checks, failed_step). Branch on code + class, never on the human-readable message. The full status/class matrix — every 4xx and 5xx, its cause, and its fix — is in the Errors reference. The one you will hit first while wiring auth:

Code	Meaning	Fix
`401`	`invalid API key`	Key not in this environment’s store — a `phosra_test_` key only works against the sandbox, `phosra_live_` only against production.
`403`	`no API scopes in context`	Request reached a `/developer/*` route with no `phosra_` key at all — attach `Authorization: Bearer $PHOSRA_API_KEY`.
`403`	`missing required scope: …`	Key authenticated but lacks the scope — mint a key with the scope named in the message.
`429`	rate limited	Wait until `X-RateLimit-Reset`, then retry.
`500`	internal error	Transient — retry with exponential backoff.

Base URLs

Environment	Base URL
Production	`https://prodapi.phosra.com/api/v1`
Sandbox	`https://phosra-api-sandbox-production.up.railway.app/api/v1` — seeded demo family + `phosra_test_` keys
Local dev	`http://localhost:8080/api/v1`

api.phosra.com has no DNS record — do not use it. Use prodapi.phosra.com for production.

Checklist

Account created via WorkOS AuthKit
Developer org created and API key provisioned (test and production)
Quick setup tested with a sandbox child
At least one platform connected; enforcement_mode checked
Enforcement triggered and results polled (not webhook-waited)
Error handling implemented for 4xx and 5xx responses

Get Started

Concepts

Guides

Cookbook

Partner Integration

Phosra Link (secret-free)

OCSS Conformance

Platform

1. Create Your Account

2. Get an API Key

3. Use Quick Setup for Onboarding

4. Connect Platforms

5. Register Webhooks

6. Trigger Enforcement

Handle errors

Base URLs

Checklist

​1. Create Your Account

​2. Get an API Key

​3. Use Quick Setup for Onboarding

​4. Connect Platforms

​5. Register Webhooks

​6. Trigger Enforcement

​Handle errors

​Base URLs

​Checklist

1. Create Your Account

2. Get an API Key

3. Use Quick Setup for Onboarding

4. Connect Platforms

5. Register Webhooks

6. Trigger Enforcement

Handle errors

Base URLs

Checklist