> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Storefront agents

> Browse the sales, signal, creative, and outcome agents registered to your storefront and run their OAuth flows

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:

```
https://api.apostra.com/api/v2/storefront
```

Authenticate every request with `Authorization: Bearer $SCOPE3_API_KEY`.

<Note>
  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](/v2/reference/public-callback-url-requirements).
</Note>

## 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](/v2/concepts/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

<CardGroup cols={2}>
  <Card title="Create an Agent" href="/v2/storefront/agents/tasks/create-agent" icon="plus">
    `POST /agents` — register a private Agent for your organization
  </Card>

  <Card title="List agents" href="/v2/storefront/agents/tasks/list-agents" icon="list">
    `GET /agents` — registered agents, filterable by type, status, and
    relationship
  </Card>

  <Card title="Get agent" href="/v2/storefront/agents/tasks/get-agent" icon="magnifying-glass">
    `GET /agents/{agentId}` — full agent detail with account flags
  </Card>

  <Card title="Publish connection setup" href="/v2/storefront/agents/connection-setup" icon="plug-circle-plus">
    Define, preview, and publish the immutable non-secret contract publishers
    use
  </Card>

  <Card title="Start agent OAuth" href="/v2/storefront/agents/tasks/start-agent-oauth" icon="key">
    `POST /agents/{agentId}/oauth/authorize` — agent-level token flow
  </Card>

  <Card title="Start account OAuth" href="/v2/storefront/agents/tasks/start-account-oauth" icon="user-lock">
    `POST /agents/{agentId}/accounts/oauth/authorize` — per-account token flow
  </Card>
</CardGroup>