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

# Marketplace listing lifecycle and trust model

> What the developer marketplace is, how a listing moves from draft to published through platform review, the four listing types, what installing actually copies, and why the catalog is safe to browse and install from.

# Marketplace listing lifecycle and trust model

The developer marketplace is a catalog of agent templates, flow templates, integrations, and agent tool packs published by Devotel and by other Orbit builders. The endpoint contract — every field, every status value — lives in the [Marketplace API reference](/api-reference/marketplace); the task-level walkthrough is [Browse, install, and publish](/guides/marketplace-browse-install-publish). This page explains the model behind both: why browsing is unauthenticated, how a listing earns the right to be installed cross-tenant, and what trust guarantees hold for everything in the published catalog.

## What the marketplace is

Build once, install anywhere. A builder authors a working agent, flow, integration, or tool inside their own Orbit organization, publishes the definition to the marketplace, and any other tenant can install it as a starting point for their own workspace. Devotel also ships built-in agent templates (support triage, SMS routing, FAQ bots, vertical voice agents) that appear in the catalog alongside tenant-built listings.

The browse endpoints — `POST`-free `GET /marketplace` and `GET /marketplace/:id` — are deliberately **unauthenticated**. A marketplace you must sign up for before you can even look at it is a marketplace nobody compares, so the catalog is a plain read: embed it in a public page, script it from a CLI, or let a prospect evaluate a template before creating an account. Unauthenticated access is safe because of the lifecycle below — the public read path only ever serves listings a platform reviewer has approved, and it serves them without exposing which organization authored unpublished work.

## The listing lifecycle

A listing carries one `status` value at a time, and the walk is linear:

| Status           | Meaning                                                      | Who can see it                                                                                               |
| ---------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| `draft`          | Authored, not yet submitted. The start state.                | The author's organization only (`GET /marketplace/mine`).                                                    |
| `pending_review` | Submitted and waiting on a platform reviewer's verdict.      | The author's organization, plus the moderation queue.                                                        |
| `published`      | Approved by a reviewer. The only state consumers ever reach. | Everyone — the public catalog, and installable by any tenant.                                                |
| `rejected`       | Refused by a reviewer, or pulled after publication.          | The author's organization — the reviewer's note lands on the listing row so the author can fix and resubmit. |

The typical walk is `draft → pending_review → published`, with `rejected` as a loop back into `draft` after an edit. Authors can only ever move their own listing between `draft` and `pending_review`; the two verdict states are writable only by a platform reviewer. An author attempting to self-publish receives 403, so no listing becomes publicly installable without the review gate.

Moderators work the queue in the admin console at **Dashboard → Marketplace** (admin.orbit.devotel.io): a pending-review list ordered oldest submission first, a full config preview before each verdict, and the published catalog with a takedown action for post-launch problems. A submission moves into any other `pending_review` item only once, and a second verdict attempt on the same listing fails rather than overwriting the first — the queue cannot be raced.

Drafts never enter the queue at all. A reviewer only sees work the author explicitly submitted, so iterating in private costs nothing.

## Listing types

The `type` field declares what installing a listing produces:

* **`agent_template`** — a complete agent definition (system prompt, model, tools). Installing one materializes a new agent in draft status inside your workspace.
* **`flow_template`** — a conversational or automation graph copied into your tenant.
* **`integration`** — configuration for a channel or external system connection.
* **`agent_tool`** — a reusable custom-tool definition (name, description, JSON-Schema parameters, execution mode, retry policy). This publishes a *template* other tenants install as a starting point for their own tool, not a one-off flow step.

Only the fourth type has a special rule, covered below in security posture.

## Install semantics

Installing is a **one-time copy, not a live link**. The moment an install completes, the resolved configuration lands inside the installing tenant's schema as that tenant's own resource. The author cannot edit what you installed, and a later version of the listing never mutates your copy — publish a takedown and every existing install keeps working. Deleting a listing removes it from the catalog but, again, installed copies stay.

Two consequences follow. First, installing is idempotent for agent templates: re-installing the same one returns the agent you already created rather than a duplicate, so an install call is always safe to retry after a timeout. Second, paid listings settle at install: the price the builder set is deducted from the installer's wallet before the copy is created, and the builder organization is credited their share minus the platform fee — the same split math the rev-share preview endpoint reports. The charge and the payout either both complete or the install fails; a failed install never leaves a charge behind.

## Security posture

Everything in a listing's `config` blob — the system prompt, flow graph, integration settings, or tool definition — is publicly readable the moment the listing is published. That is the point of a template, and it is also the constraint: **never put secrets in `config`.** API keys, webhook secrets, and credentials in a published listing are readable by anyone with no credential of their own.

The clearest case is `agent_tool` listings: a tool definition carries an executor URL, and the naive shape would include the executor secret. Tool listings are hard-rejected (422 on create or update) if `config.executor_secret` is present at all — installers configure their own executor secret after installing, so no live credential ever travels through the catalog. This is a reject-don't-strip rule: the author gets a clear failure instead of a listing that silently lost a field.

Review adds the second layer. A moderator previews the full config before approving, rejecting notes-required, and can take down a live listing with a reason — so a problem discovered post-launch has a path back out of the catalog that the audit trail can explain.

## Roles and auth

Write paths — create, update, delete, install, and the author-scoped `/marketplace/mine` list — require an authenticated caller with an `owner`, `admin`, or `developer` role on the key or session. Public reads require nothing. Rate limits mirror the split: 60 requests per minute on the public reads, 10 per minute on the writes, so the catalog is meant to be browsed far more often than edited.

## Why this page exists

Three platform guarantees meet in this model, and they are why a published marketplace listing is safe to install. Per-tenant provisioning means an install resolves into your own schema — nothing about a published template escapes review to mutate you later. The review queue means only reviewer-approved definitions ever reach the public catalog or another tenant's install call. And revenue-share accounting means a paid install settles atomically: the builder's payout is computed with the same split math the platform reports, so the monetization promise and the trust model hold under the same ledger. For the operational walkthrough of each step, see [Browse, install, and publish](/guides/marketplace-browse-install-publish).

## See also

* [Marketplace API reference](/api-reference/marketplace) — the endpoint contract this page explains
* [Browse, install, and publish](/guides/marketplace-browse-install-publish) — the task-level walkthrough
* [Developer Portal](/guides/developer-portal) — API keys and roles for the write endpoints
* [Rate limits](/guides/rate-limits) — how the public-read and write buckets behave