Skip to main content
A storefront agent is an agent registered for use with your storefront — a sales/media agent, a signal/data agent, a creative agent, or an outcome measurement agent. Your organization can own the Agent (SELF) or use one from the wider marketplace (MARKETPLACE). Each Agent also carries capability metadata (type, protocol, authenticationType) and a lifecycle status. List and inspect Agents to decide which ones power your storefront and which need authorization. Agents that use OAuth need an interactive consent flow before the platform can call them. There are two flows: agent-level OAuth stores tokens in the agent configuration for platform-to-agent calls, and per-account OAuth stores tokens against the buyer/operator account the grant represents. Both return an authorizationUrl you send the operator to. All examples use the storefront base URL:
Authenticate every request with Authorization: Bearer $SCOPE3_API_KEY.
Partner-agent endpoint URLs must be directly reachable public HTTPS endpoints. Private-network, localhost, DNS-rebound, and redirecting URLs are rejected when you create or update an agent. See Public callback URL requirements.

​
Manage an Agent in Murph

Agents is a full workspace alongside Inventory and Advertisers. Choose Agents in the left navigation to open the collection in the main canvas. Select an Agent, then use its workspace navigation to move between:
  • Overview for identity, ownership, current status, and the next action.
  • Endpoint & protocol for the shared, non-secret endpoint contract.
  • Test & certify for validation and Sales Agent certification status.
  • Inventory sources for the exact Sales Agent deployments you can access.
Credentials, connection tests, and diagnostics belong to an exact Inventory Source. Open that source from Inventory sources instead of looking for source-specific secrets or failures on the Agent itself. Other Agent roles show only the sections supported by their authorized connection contract. See Agents for the ownership and navigation model.

​
Register an observed implementation

When Apostra observes that an owned Agent implementation changed, a direct organization administrator can use Register current implementation on the Agent Overview. The Task derives the exact current observation on the server and creates an immutable production revision and deployment; it never asks you to provide a hash, deployment reference, or Partner registration. This action does not pause, deselect, or stop an active Inventory Source. It records the implementation that certification applies to. A changed implementation or stale certification can still require revalidation before new client connections or certification work proceeds.

​
Run a no-spend transaction validation

Open Test & certify on an Agent you own and choose an available validation profile for its current revision. The transaction profile uses an isolated, no-spend sandbox. Starting it can prepare temporary sandbox resources, but it does not stage a media buy or activate a campaign without confirmation. The page shows Confirm sandbox step before staging a media buy and again before activating the sandbox campaign. Review each pending action, then confirm it in that same Agent page. Each confirmation is bound to the exact validation run, Agent revision, generation, and pending step; it cannot approve a different run or a later retry. If a confirmation is expired, cancelled, or has already been used, start a new validation instead of retrying the old control. After the confirmation, the run continues from its server-recorded checkpoint. Its result names the exact implementation revision and reports the cleanup outcome. Read the Agent’s certification and diagnostics after the run: a passed validation is evidence for the revision it names, not a certificate or an authorization for a client connection.

​
Task reference

Create an Agent

POST /agents — register a private Agent for your organization

List agents

GET /agents — registered agents, filterable by type, status, and relationship

Get agent

GET /agents/{agentId} — full agent detail with account flags

Publish connection setup

Define, preview, and publish the immutable non-secret contract publishers use

Start agent OAuth

POST /agents/{agentId}/oauth/authorize — agent-level token flow

Start account OAuth

POST /agents/{agentId}/accounts/oauth/authorize — per-account token flow