Developer Platform Overview

The Phosra developer platform is the live control-plane API for building on top of Phosra’s OCSS-conformant infrastructure. It covers the management operations your integration needs before sending a single signed verb: create a developer org, provision phosra_-prefixed API keys, register advisor agents, declare OCSS payload keys for federation, mint MCP tokens, and pull hourly usage rollups. Base URL: https://prodapi.phosra.com/api/v1
Authentication: HTTP Bearer — a WorkOS session bearer (from signup/login) for org and key management, a phosra_ API key for the /developer/* data-plane routes
Status: Live — see /ocss/status for current availability and preview labels

No key needed to get your first key. Org creation and key minting authenticate with your WorkOS session, so a fresh signup bootstraps everything self-serve — see Create your account & get keys.

This is the Phosra control plane — the management surface for developers integrating with OCSS via Phosra. It is distinct from the Parental Controls product API (Phosra’s own consumer product, a separate pillar documented elsewhere).

Building a platform that enforces rules? None of the operations on this page are the ones you need. A platform runs createPlatform from @phosra/gatekeeper and authenticates with an operator-issued PHOSRA_CREDENTIAL, not a phosra_ key or a session bearer — and it must additionally publish a census directory row and serve its own profiles endpoint before it will boot. Start at @phosra/gatekeeper → createPlatform, then the readiness contract.

What the control plane covers

Area	Description
Organizations	Create and manage developer orgs — the billing and access boundary for your integration.
API keys	Provision, revoke, and rotate `phosra_`-prefixed keys. Keys are shown once at creation.
Usage	Hourly request rollups per org — query windowed by `from` / `to` timestamps.
Advisor agents	Register OCSS advisor agents, submit consultation requests, and declare Ed25519 payload keys for federation.
MCP tokens	Mint and revoke Model Context Protocol authentication tokens for AI-agent integrations.

Operations reference

All 17 control-plane operations, their routes, and their authentication requirements:

Function	Method + path	Auth
`listOrgs`	`GET /developers/orgs`	session bearer
`createOrg`	`POST /developers/orgs`	session bearer
`getOrg`	`GET /developers/orgs/{orgId}`	session bearer
`updateOrg`	`PUT /developers/orgs/{orgId}`	session bearer
`deleteOrg`	`DELETE /developers/orgs/{orgId}`	session bearer
`listOrgMembers`	`GET /developers/orgs/{orgId}/members`	session bearer
`listApiKeys`	`GET /developers/orgs/{orgId}/keys`	session bearer
`createApiKey`	`POST /developers/orgs/{orgId}/keys`	session bearer
`revokeApiKey`	`DELETE /developers/orgs/{orgId}/keys/{keyId}`	session bearer
`regenerateApiKey`	`POST /developers/orgs/{orgId}/keys/{keyId}/regenerate`	session bearer
`getOrgUsage`	`GET /developers/orgs/{orgId}/usage`	session bearer
`registerAdvisor`	`POST /advisors/register` (deprecated — forwards to `/advisors/self-register`)	session bearer
`consultAdvisor`	`POST /advisors/consult`	session bearer
`declareAdvisorPayloadKey`	`POST /advisors/{id}/payload-key`	Ed25519 possession
`listMcpTokens`	`GET /mcp-tokens`	session bearer
`createMcpToken`	`POST /mcp-tokens`	session bearer
`revokeMcpToken`	`DELETE /mcp-tokens/{id}`	session bearer

All management operations (/developers/orgs*, keys, usage, advisors, MCP tokens) use a session bearer — the WorkOS access token from your signup/login session. This is deliberate: it means a fresh signup can create an org and mint its first phosra_ key with no pre-existing key (Create your account & get keys). The phosra_ key you mint authenticates the data-plane /developer/* routes (families, policies, enforcement — see Authentication), not these management calls. declareAdvisorPayloadKey additionally requires Ed25519 key possession — the request must be signed with the advisor’s existing registered signing key (not the new payload key being declared); see Declare payload key for the exact signed preimage.

`@phosra/sdk-dev` management half

The management half of @phosra/sdk-dev is a generated TypeScript client produced from the Phosra OpenAPI spec by hey-api. Each operation is a typed function that accepts an Options<…Data> object and returns a RequestResult — a Promise resolving to { data, error }.

@phosra/sdk-dev is a preview package — the shape is committed and the control-plane API it calls is live, but the package is not yet published to npm. See /ocss/status for the current preview label and availability timeline.

Configure the client

import { client } from "@phosra/sdk-dev";

client.setConfig({
  baseUrl: "https://prodapi.phosra.com/api/v1",
  headers: {
    // Management calls (orgs, keys, usage) take your WorkOS session bearer.
    // Use the phosra_ key you mint for the /developer/* data-plane routes.
    Authorization: `Bearer ${process.env.WORKOS_ACCESS_TOKEN}`,
  },
});

Override baseUrl with http://localhost:8080/api/v1 for local development.

Create a developer organization

import { createOrg } from "@phosra/sdk-dev";

const { data, error } = await createOrg({
  body: {
    name: "Acme Corp",
    description: "Acme's OCSS integration",
    website_url: "https://acme.example.com",
  },
  headers: {
    Authorization: `Bearer ${process.env.WORKOS_ACCESS_TOKEN}`,
  },
});

if (error) {
  // error.message, error.code, error.error (HTTP status text)
  throw new Error(`createOrg failed: ${error.message}`);
}

console.log("Created org:", data.id, data.slug);

WORKOS_ACCESS_TOKEN is the session bearer from your WorkOS signup/login — no phosra_ key exists yet at this point, and none is needed. Once the org exists, createApiKey (same session bearer) mints your first phosra_-prefixed key.

One-time secrets

DeveloperApiKeyWithSecret.key and CreatedMcpToken.plain are returned only once — at create or regenerate time — and are never stored server-side. Save them immediately.

Base URLs

Environment	Base URL
Production	`https://prodapi.phosra.com/api/v1`
Local dev	`http://localhost:8080/api/v1`

Get Started

Concepts

Guides

Cookbook

Partner Integration

Phosra Link (secret-free)

OCSS Conformance

Platform

What the control plane covers

Operations reference

`@phosra/sdk-dev` management half

Configure the client

Create a developer organization

One-time secrets

Base URLs

Further reading

​What the control plane covers

​Operations reference

​@phosra/sdk-dev management half

​Configure the client

​Create a developer organization

​One-time secrets

​Base URLs

​Further reading

What the control plane covers

Operations reference

`@phosra/sdk-dev` management half

Configure the client

Create a developer organization

One-time secrets

Base URLs

Further reading