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 with a phosra_ API key
Status: Live — see /ocss/status for current availability and preview labels

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).

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`	`phosra_` key
`createOrg`	`POST /developers/orgs`	`phosra_` key
`getOrg`	`GET /developers/orgs/{orgId}`	`phosra_` key
`updateOrg`	`PUT /developers/orgs/{orgId}`	`phosra_` key
`deleteOrg`	`DELETE /developers/orgs/{orgId}`	`phosra_` key
`listOrgMembers`	`GET /developers/orgs/{orgId}/members`	`phosra_` key
`listApiKeys`	`GET /developers/orgs/{orgId}/keys`	`phosra_` key
`createApiKey`	`POST /developers/orgs/{orgId}/keys`	`phosra_` key
`revokeApiKey`	`DELETE /developers/orgs/{orgId}/keys/{keyId}`	`phosra_` key
`regenerateApiKey`	`POST /developers/orgs/{orgId}/keys/{keyId}/regenerate`	`phosra_` key
`getOrgUsage`	`GET /developers/orgs/{orgId}/usage`	`phosra_` key
`registerAdvisor`	`POST /advisors/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

Most management operations (/developers/orgs*, /developers/orgs/{orgId}/keys*, /developers/orgs/{orgId}/usage) use a phosra_-prefixed API key. Advisor and MCP token operations use a session bearer (short-lived token issued at login). declareAdvisorPayloadKey additionally requires Ed25519 key possession — the request must be signed with the declared key.

`@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

typescript

import { client } from "@phosra/sdk-dev";
 
client.setConfig({
  baseUrl: "https://prodapi.phosra.com/api/v1",
  headers: {
    Authorization: `Bearer ${process.env.PHOSRA_API_KEY}`,
  },
});

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

Create a developer organization

typescript

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.PHOSRA_API_KEY}`,
  },
});
 
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);

PHOSRA_API_KEY is a developer-tier key with the phosra_ prefix, issued to your developer account.

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`