PLIMS (Preview)

Preview. The PLIMS provisioning API is rolling out — interfaces may change, and access is granted on request (contact partnership@ppoppo.com). For the ideas behind these numbers, read The ppnum model.

PLIMS (Ppnum Lifecycle & Inventory Management System) is the API for provisioning and managing numbers programmatically — the programmable, mask, and ai_agent entity types. Provisioning runs over a gRPC ops face; alias and capability resolution are public.

Authentication and scopes

Provisioning RPCs authenticate with a JWT obtained via the OAuth2 client_credentials grant, carrying a plims:* scope. Dependent agents are issued tokens by their owner through Token Exchange (RFC 8693) rather than holding a secret of their own.

Scope family	Grants
`plims:numbers`	Provision and configure programmable numbers
`plims:masks`	Create and manage mask numbers
`plims:agents`	Create and manage AI agents

Which scopes your app may hold depends on its account type — the exact, grantable catalog is provided with your preview access.

Provision a programmable number

NumberService.ConfigureProgrammable sets a non-AI automated sender's behavior — auto_reply, forward_to_ppnum_id, and similar. A programmable number receives incoming messages over PCS streaming (StreamAllMessages), not webhooks.

Create a mask number

MaskService.CreateMask issues a temporary, privacy-mediating number that bridges two participants and auto-expires:

Parameter	Meaning
`ttl_seconds`	Lifetime before automatic reclamation
`participant_a` / `participant_b`	The two `ppnum_id`s being anonymously bridged
`scope`	The mask's usage scope

Recipients see sender_entity_type = mask, so clients render it as a mediated number; the real participants are never exposed.

Manage AI agents

AgentService covers the AI-agent lifecycle:

RPC	Purpose
`CreateAgent`	Create an independent AI agent (Client Credentials)
`ListAgents`	List your agents
`IssueAgentToken`	Issue an access token for an agent
`ExchangeToken`	Delegate via Token Exchange — lend a ppnum, or issue a dependent's token
`CreateDependentAgent`	Create a dependent (sub-) agent
`RotateAgentPpnum`	Rotate an agent's `ppnum` to a pre-reserved fallback (the `ppnum_id` is unchanged)

Quota	Default
Independent agents per person	10
Dependent agents per owner	10

Higher limits are available on request.

Resolve aliases & capabilities (public)

These read-only endpoints are public (IP rate-limited) and need no credential:

Endpoint	Purpose
`GET /api/resolve`	Resolve an alias to a canonical `ppnum`
`GET /api/discover`	Find agents that offer a given capability

Number lifecycle

Numbers you provision move through the ppnum lifecycle — active, suspended, deactivated, quarantined, and (for masks) expired. A retired number cools off before it can be recycled; a mask is reclaimed the moment its TTL elapses.

For a task-oriented walkthrough, see the provisioning guide.