> ## 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.
# Rotate a bound endpoint's label
> Issues a fresh §9.3(b) label for the binding identified by {id} (UUID from the mint response). The prior label is invalidated immediately. The new label is returned once; it is never logged. Returns only endpoint_id_label (connect_secret is not rotated; it stays fixed per binding).
Issues a **fresh §9.3(b) label** for the binding identified by `{id}` (the `binding_id` from
[the bind response](/api-reference/data-plane/bind-endpoint)). The prior label is invalidated
**immediately** — a subsequent profile GET on the old label returns `404`. Only
`endpoint_id_label` is returned; the `connect_secret` is **not** rotated (it stays fixed per
binding).
Rotate on your window cadence to keep the bound-resolver label short-lived. Because rotation is
atomic and the old label dies instantly, poll the new label before discarding the old one only
if you cannot tolerate a single missed cycle.
## Worked example
```ts Node theme={null}
import { signRequest } from "@openchildsafety/ocss"
const BASE = "https://phosra-api-sandbox-production.up.railway.app/api/v1"
const seed = new Uint8Array(Buffer.from("bG9vcGxpbmUBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQE", "base64url"))
const keyID = "did:ocss:loopline#2026-06"
const bindingId = "c8ff82dd-4aa8-4a52-a235-ae13717eb4c8" // from the bind response
const targetURI = `${BASE}/enforcement-endpoints/${bindingId}/rotate`
const headers = signRequest({ method: "POST", targetURI, body: new TextEncoder().encode("{}"), keyID, seed, created: Math.floor(Date.now() / 1000) })
headers["Content-Type"] = "application/json"
const res = await fetch(targetURI, { method: "POST", headers, body: "{}" })
console.log(res.status, await res.json())
```
```python Python theme={null}
# sign_request(...) — the signer from /concepts/signing-requests.
import requests
BASE = "https://phosra-api-sandbox-production.up.railway.app/api/v1"
SEED = "bG9vcGxpbmUBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQE"
KEYID = "did:ocss:loopline#2026-06"
binding_id = "c8ff82dd-4aa8-4a52-a235-ae13717eb4c8" # from the bind response
url = f"{BASE}/enforcement-endpoints/{binding_id}/rotate"
body = b"{}" # rotate has an empty JSON body
h = sign_request("POST", url, KEYID, SEED, body)
h["Content-Type"] = "application/json"
res = requests.post(url, data=body, headers=h)
print(res.status_code, res.json()) # -> 200 { endpoint_id_label }
```
```go Go theme={null}
// SignRequest(...) — the stdlib signer from /concepts/signing-requests.
package main
import (
"bytes"; "fmt"; "io"; "net/http"
)
func main() {
const (
base = "https://phosra-api-sandbox-production.up.railway.app/api/v1"
seed = "bG9vcGxpbmUBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQE"
keyID = "did:ocss:loopline#2026-06"
bindingID = "c8ff82dd-4aa8-4a52-a235-ae13717eb4c8" // from the bind response
)
url := base + "/enforcement-endpoints/" + bindingID + "/rotate"
body := []byte("{}") // rotate has an empty JSON body
h, _ := SignRequest("POST", url, keyID, seed, body)
req, _ := http.NewRequest("POST", url, bytes.NewReader(body))
for k, v := range h {
req.Header.Set(k, v)
}
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
b, _ := io.ReadAll(resp.Body)
fmt.Println(resp.StatusCode, string(b)) // -> 200 { endpoint_id_label }
}
```
```bash curl + openssl theme={null}
# Runnable signed openssl script: /concepts/signing-requests (swap the POST target for this
# rotate URL and use an empty body `{}`). Wire shape of the four headers:
curl -X POST https://phosra-api-sandbox-production.up.railway.app/api/v1/enforcement-endpoints/c8ff82dd-4aa8-4a52-a235-ae13717eb4c8/rotate \
-H "Content-Type: application/json" \
-H "OCSS-Spec-Version: OCSS-v1.0-pre" \
-H 'Content-Digest: sha-256=::' \
-H 'Signature-Input: ocss=("@method" "@target-uri" "ocss-spec-version" "content-digest");created=1783315514;keyid="did:ocss:loopline#2026-06";alg="ed25519"' \
-H 'Signature: ocss=::' \
-d '{}'
```
The `sign_request` / `SignRequest` helper is defined once in the
[**request-signing guide**](/concepts/signing-requests) — its Python, Go, and `curl+openssl`
recipes are verified against this sandbox. Even an empty-body `POST` covers `content-digest`
(over the bytes `{}`).
**Real `200` response** (captured from the hosted sandbox):
```json theme={null}
{
"endpoint_id_label": "cOxEaug6hEkbx8lYQOM8NiBtLknSSup5zqXvMjRfHa8"
}
```
The prior label (`iGrFqzp4…`) now returns `404` on
[`GET /enforcement-profiles/{endpoint_id}`](/api-reference/data-plane/fetch-profile).
## OpenAPI
````yaml POST /enforcement-endpoints/{id}/rotate
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:
/enforcement-endpoints/{id}/rotate:
post:
summary: Rotate a bound endpoint's label
description: >
Issues a fresh §9.3(b) label for the binding identified by {id} (UUID
from the mint response). The prior label is invalidated immediately. The
new label is returned once; it is never logged. Returns only
endpoint_id_label (connect_secret is not rotated; it stays fixed per
binding).
operationId: rotateABoundEndpointSLabel
parameters:
- name: id
in: path
required: true
description: Binding UUID from the mint response (binding_id).
schema:
type: string
format: uuid
responses:
'200':
description: Rotated. New label replaces the prior one immediately.
content:
application/json:
schema:
$ref: '#/components/schemas/EndpointRotateResponse'
example:
endpoint_id_label: a-bmtAOYzb-Yhhnw11lZtOLFPwD_ms0fnRNQnNgRe-Q
'400':
description: The path `id` is not a well-formed UUID. `class` is `malformed`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Bad Request
message: id must be a uuid
code: 400
class: malformed
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: No binding exists for this UUID. `class` is `not_found`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Not Found
message: unknown enforcement endpoint
code: 404
class: not_found
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/ServerError'
'502':
$ref: '#/components/responses/BadGateway'
'503':
description: >
The census operation is not yet available on this deployment
(feature-gated surface). Retry later.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Service Unavailable
message: census operation not yet available
code: 503
security:
- Rfc9421Signature: []
x-codeSamples:
- lang: Shell
label: Signed curl (wire shape)
source: >
# Signed headers are per-request — compute with the SDK (Node tab).
Body is {}.
curl -X POST
https://phosra-api-sandbox-production.up.railway.app/api/v1/enforcement-endpoints/c8ff82dd-4aa8-4a52-a235-ae13717eb4c8/rotate
\
-H "Content-Type: application/json" \
-H "OCSS-Spec-Version: OCSS-v1.0-pre" \
-H 'Signature-Input: ocss=("@method" "@target-uri" "ocss-spec-version" "content-digest");created=1783315514;keyid="did:ocss:loopline#2026-06";alg="ed25519"' \
-H 'Signature: ocss=::' \
-H 'Content-Digest: sha-256=::' \
-d '{}'
- lang: JavaScript
label: Node (@openchildsafety/ocss)
source: >
import { signRequest } from "@openchildsafety/ocss"
const BASE =
"https://phosra-api-sandbox-production.up.railway.app/api/v1"
const seed = new
Uint8Array(Buffer.from("bG9vcGxpbmUBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQE",
"base64url"))
const keyID = "did:ocss:loopline#2026-06"
const bindingId = "c8ff82dd-4aa8-4a52-a235-ae13717eb4c8"
const t = `${BASE}/enforcement-endpoints/${bindingId}/rotate`
const h = signRequest({ method: "POST", targetURI: t, body: new
TextEncoder().encode("{}"), keyID, seed, created:
Math.floor(Date.now() / 1000) })
h["Content-Type"] = "application/json"
const res = await fetch(t, { method: "POST", headers: h, body: "{}"
})
console.log(res.status, await res.json())
components:
schemas:
EndpointRotateResponse:
type: object
description: >
Binding rotation result. Source: EndpointHandlers.Rotate response in
internal/ocsshttp/handler_endpoints.go. Returns a fresh label only.
required:
- endpoint_id_label
properties:
endpoint_id_label:
type: string
description: >
Rotated high-entropy §9.3(b) label. Replaces the prior label
immediately; the prior label returns 404 after rotation. Never log.
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:
Unauthorized:
description: >
RFC 9421 message-signature authentication failed. Every data-plane call
must carry exactly one `Signature-Input` and one `Signature` header
computed over the request with your Trust-List-published Ed25519 key.
`class` is `signature_invalid`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Unauthorized
message: exactly one Signature-Input and one Signature header are required
code: 401
class: signature_invalid
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
securitySchemes:
Rfc9421Signature:
type: http
scheme: signature
description: >
RFC 9421 message signature (Ed25519). The sender signs the request with
its Trust-List-published key; the census verifies provenance and
accreditation tier before processing. Used for POST
enforcement-endpoints (binding mint), POST
enforcement-endpoints/{id}/rotate, and POST enforcement-confirmations.
Profile GETs (GET /enforcement-profiles/{endpoint_id}) also require the
resolver's RFC 9421 signature — the §9.3(b) bound-resolver auth.
````