> ## 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.
# Reference profiles leg — child list (sandbox)
> SANDBOX-ONLY. Returns a BARE JSON ARRAY of the seeded sandbox child profiles (Mia/Leo/Ava) for a valid `Authorization: Bearer sbxtok_…` token. Gated on the Restricted band. Source: internal/ocsshttp/handler_sandbox_oauth.go Profiles().
**Sandbox only.** Hosted on the census **host root** (not `/api/v1`), gated on
`PHOSRA_ENV==sandbox` — `404` elsewhere.
Returns a **bare JSON array** of the seeded sandbox child profiles (Mia / Leo / Ava) for a
valid `Authorization: Bearer sbxtok_…` token from
[`POST /oauth/token`](/api-reference/data-plane/oauth-token). The response is **not wrapped in
an object** — it is the array itself.
## Worked example
Fully runnable — supply a token from the token leg:
```bash Shell theme={null}
curl https://phosra-api-sandbox-production.up.railway.app/oauth/profiles \
-H "Authorization: Bearer sbxtok_9xRWtUBLsk1omBYjWWe-20KbCxTO1Noh"
```
```ts Node theme={null}
const BASE = "https://phosra-api-sandbox-production.up.railway.app"
const res = await fetch(`${BASE}/oauth/profiles`, {
headers: { Authorization: "Bearer sbxtok_9xRWtUBLsk1omBYjWWe-20KbCxTO1Noh" },
})
const profiles = await res.json() // bare array
console.log(res.status, profiles.map((p) => p.displayName)) // 200 [ 'Mia', 'Leo', 'Ava' ]
```
**Real `200` response** (captured from the hosted sandbox):
```json theme={null}
[
{ "id": "mia", "displayName": "Mia", "subject_ref": "a11ce0fa-0000-4000-8000-0000000000a1", "kind": "child" },
{ "id": "leo", "displayName": "Leo", "subject_ref": "a11ce0fa-0000-4000-8000-0000000000a2", "kind": "child" },
{ "id": "ava", "displayName": "Ava", "subject_ref": "a11ce0fa-0000-4000-8000-0000000000a3", "kind": "child" }
]
```
A missing or non-`sbxtok_` bearer token returns `401 invalid_token`. The `subject_ref` is the
stable child id that downstream policy and enforcement legs key on.
## OpenAPI
````yaml GET /oauth/profiles
openapi: 3.1.0
info:
title: Phosra OCSS Data Plane — enforcement endpoints, profiles & confirmations
description: >
The signed OCSS data-plane the @phosra/gatekeeper SDK drives. These are NOT
plain REST: profile GETs are RFC 9421-signed by the resolver, binding POSTs
require accredited caller signatures, and profile responses are
root-verifiable signed documents consumed via @openchildsafety/ocss /
@phosra/gatekeeper. This spec documents the wire shapes for client
generation; it does not change census behavior. The control plane (provider
org, keys, advisors) is in openapi.control-plane.yaml; the parental-control
product API is in openapi.yaml.
Canonical profile shape: `categories[]` (there is no `rules[]` field — it
does not exist on the wire, in the Go model, or in @phosra/gatekeeper
types).
Wire shapes are authoritative from the Go census:
- profile.Document / CategoryEntry: internal/ocss/profile/document.go
- EndpointHandlers.Mint / Rotate: internal/ocsshttp/handler_endpoints.go
- ProfileReads.ServeHTTP: internal/ocsshttp/handler_profiles.go
- EnforcementHandlers.Confirm: internal/ocsshttp/handler_enforcement.go
- receipt.Receipt / EnforcementResultBody: internal/ocss/receipt/types.go
version: 1.0.0
license:
name: Proprietary
url: https://phosra.com/terms
contact:
name: Phosra
servers:
- url: https://phosra-api-sandbox-production.up.railway.app/api/v1
description: >-
Hosted sandbox — the one canonical, stable, partner-facing testing
endpoint
- url: http://localhost:8080/api/v1
description: Local development
security: []
paths:
/oauth/profiles:
servers:
- url: https://phosra-api-sandbox-production.up.railway.app
description: Sandbox census host ROOT — the /oauth/* surface is NOT under /api/v1.
get:
summary: Reference profiles leg — bearer-scoped child list (sandbox only)
description: >
SANDBOX-ONLY. Returns a BARE JSON ARRAY of the seeded sandbox child
profiles (Mia/Leo/Ava) for a valid `Authorization: Bearer sbxtok_…`
token. Gated on the Restricted band. Source:
internal/ocsshttp/handler_sandbox_oauth.go Profiles().
operationId: referenceProfilesLegBearerScopedChildListSandboxOnly
responses:
'200':
description: Bare array of child profiles (NOT wrapped in an object).
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/SandboxOAuthProfile'
example:
- id: mia
displayName: Mia
subject_ref: a11ce0fa-0000-4000-8000-0000000000a1
kind: child
- id: leo
displayName: Leo
subject_ref: a11ce0fa-0000-4000-8000-0000000000a2
kind: child
- id: ava
displayName: Ava
subject_ref: a11ce0fa-0000-4000-8000-0000000000a3
kind: child
'401':
description: >
Missing, or a non-`sbxtok_` bearer token. Compact `{error:
"invalid_token"}` OAuth-style body.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: invalid_token
'404':
description: >
Not a sandbox census (gated). The route is not mounted off the
sandbox, so the router answers with a plain-text chi 404, not a JSON
envelope.
content:
text/plain:
schema:
type: string
example: |
404 page not found
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/ServerError'
'502':
$ref: '#/components/responses/BadGateway'
'503':
$ref: '#/components/responses/ServiceUnavailable'
security:
- SandboxBearer: []
x-codeSamples:
- lang: Shell
label: curl (runnable — bearer token)
source: >
curl
https://phosra-api-sandbox-production.up.railway.app/oauth/profiles
\
-H "Authorization: Bearer sbxtok_9xRWtUBLsk1omBYjWWe-20KbCxTO1Noh"
- lang: JavaScript
label: Node (runnable)
source: >
const BASE = "https://phosra-api-sandbox-production.up.railway.app"
const res = await fetch(`${BASE}/oauth/profiles`, { headers: {
Authorization: "Bearer sbxtok_9xRWtUBLsk1omBYjWWe-20KbCxTO1Noh" } })
const profiles = await res.json() // bare array
console.log(res.status, profiles.map((p) => p.displayName)) // 200
[ 'Mia', 'Leo', 'Ava' ]
components:
schemas:
SandboxOAuthProfile:
type: object
description: >
One seeded sandbox child profile. GET /oauth/profiles returns a BARE
JSON ARRAY of these (not wrapped in an object). Source:
sandboxOAuthProfile in internal/ocsshttp/handler_sandbox_oauth.go.
required:
- id
- displayName
- subject_ref
- kind
properties:
id:
type: string
example: mia
description: Unique identifier for this resource.
displayName:
type: string
example: Mia
description: Human-readable child display name shown on the consent page.
subject_ref:
type: string
description: Stable child id downstream policy/enforcement legs key on.
example: a11ce0fa-0000-4000-8000-0000000000a1
kind:
type: string
example: child
description: Profile kind; always `child` for the seeded sandbox family.
additionalProperties: true
Error:
type: object
description: Standard error envelope returned for every 4xx and 5xx response.
properties:
error:
type: string
description: >-
Short, stable, machine-readable error class — matches the HTTP
status text (e.g. `Not Found`).
message:
type: string
description: >-
Human-readable explanation of what went wrong and, where possible,
how to fix it.
code:
type: integer
description: Numeric HTTP status code, duplicated in the body for convenience.
class:
type: string
enum:
- signature_invalid
- nonconformant
- replay
- standing_failure
- scope_failure
- malformed
- not_found
description: >
Stable machine-readable error subclass for programmatic branching.
Present on ALL seven published census (data-plane) error classes —
400⇒`malformed`, 401⇒`signature_invalid`,
403⇒`standing_failure`|`scope_failure`, 404⇒`not_found`,
409⇒`replay`, 422⇒`nonconformant`. ABSENT on the plain house 500, on
control-plane/management errors, and on the compact sandbox-lane
`{error:""}` bodies (OAuth + sandbox consent).
failed_step:
type: string
description: >
Present only on a §8.3.1 standing failure (`class:standing_failure`)
— names the §6.2 step that failed, e.g. `authority_binding`.
example:
error: Not Found
message: unknown enforcement endpoint
code: 404
class: not_found
additionalProperties: true
responses:
RateLimited:
description: >-
Too many requests. Back off and retry after the interval given in the
`Retry-After` response header.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Too Many Requests
message: rate limit exceeded
code: 429
ServerError:
description: >-
An unexpected error occurred inside Phosra. The request is safe to retry
with exponential backoff; contact support if it persists.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Internal Server Error
message: internal error
code: 500
BadGateway:
description: >-
A downstream provider returned an invalid response while Phosra was
fulfilling the request. Retry with backoff.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Bad Gateway
message: downstream provider error
code: 502
ServiceUnavailable:
description: >-
A downstream provider or dependency is temporarily unavailable. Retry
with backoff.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Service Unavailable
message: downstream provider unavailable
code: 503
securitySchemes:
SandboxBearer:
type: http
scheme: bearer
description: >
SANDBOX-ONLY opaque bearer ("sbxtok_…") issued by POST /oauth/token,
presented to GET /oauth/profiles. Not a production credential — the
sandbox reference OAuth surface is stateless and gated on
PHOSRA_ENV==sandbox.
````