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

# Marketplace API

> List your marketplace's apps and turn them on or off from your own UI or your server.

`mountEmbeddedAppMarketplace()` is built on two endpoints you can call
yourself, to show the marketplace in your own design system or to turn apps on
from your server, for example when you onboard an office.

Both take a user token with `embed:enable` as a bearer token: the same token, the
same user, as the marketplace component. They accept calls from any origin, so
your page can call them directly, and from your server.

The base URL is `https://universal.rollout.com/api/embedded-apps`.

## List the apps

```
GET /marketplaces/{marketplaceId}/apps
GET /marketplaces/{marketplaceId}/apps?appId={appId}
Authorization: Bearer USER_JWT
```

```json theme={null}
{
  "canEnable": ["user", "org"],
  "canDisable": ["user", "org"],
  "apps": [
    {
      "id": "019a7c4f-…",
      "name": "Showing Notes",
      "tagline": "Notes from every showing, on the contact.",
      "description": "…",
      "iconUrl": "https://universal.rollout.com/api/embedded-apps/app-icons/5f2c…e1.png",
      "supportUrl": "https://showingnotes.example.com/support",
      "privacyPolicyUrl": null,
      "enabled": { "user": false, "org": true }
    }
  ]
}
```

| Field | Meaning |
| - | - |
| `apps` | The apps approved in your marketplace, by name. `appId` narrows it to one. |
| `apps[].enabled.user` | The user turned it on for themselves. |
| `apps[].enabled.org` | The user's org has it on. Always `false` for a token without `embed.org`. |
| `apps[].iconUrl` | The app's icon on Rollout's origin, a PNG, JPEG or WebP image, or `null`. An icon's URL never changes what it shows, so it can be cached for good. |
| `apps[].supportUrl`, `privacyPolicyUrl` | `http` or `https` links to the publisher's pages, or `null`. |
| `canEnable` | The scopes the user may turn apps **on** for: those your marketplace allows that the token grants. |
| `canDisable` | The scopes the user may turn apps **off** for: those the token grants, whatever your marketplace allows. |

`user` is always granted. `org` is granted by `embed:enable_org` with an
`embed.org` claim.

## Turn an app on or off

```
PUT    /marketplaces/{marketplaceId}/apps/{appId}/enablements/{scope}
DELETE /marketplaces/{marketplaceId}/apps/{appId}/enablements/{scope}
Authorization: Bearer USER_JWT
```

`PUT` turns the app on, `DELETE` turns it off, for `scope` `user` (the token's
user) or `org` (the org in its `embed.org`). Both answer the app as the user
now sees it, in the shape of an entry in `apps`. Both are idempotent: turning
on an app that's already on, or off one that's already off, changes nothing.

```js theme={null}
const base = "https://universal.rollout.com/api/embedded-apps";
const response = await fetch(
  `${base}/marketplaces/${marketplaceId}/apps/${appId}/enablements/user`,
  { method: "PUT", headers: { authorization: `Bearer ${token}` } },
);
const app = await response.json(); // app.enabled.user === true
```

Turning an app on for a scope your marketplace doesn't allow answers `403
ENABLEMENT_SCOPE_NOT_ALLOWED`. Turning it off always works, so users can turn
off apps in a scope you stopped allowing.

## Showing it the way Rollout's component does

* Show a switch for each scope in `canEnable`. For an app still on in a scope
  that's in `canDisable` but not `canEnable`, show that switch too, so the
  user can turn it off.
* When `enabled.org` is true, show the user's own switch as on and disabled,
  with something like "Enabled by your org". Only an org admin can turn it off,
  for the org.
* After a change, call `refresh()` on any `mountEmbeddedApps()` handle on the
  page, so the apps follow.

## Error responses

An error answers with its HTTP status and a body naming its code:

```json theme={null}
{ "errors": [{ "code": "ENABLEMENT_SCOPE_NOT_ALLOWED", "message": "This marketplace doesn't allow enabling apps with the scope 'org'. Its owner sets the scopes it allows." }] }
```

The codes are listed under [Errors](https://embedded-apps.rollout.com/reference/errors.md). A path whose `scope` is neither
`user` nor `org` answers `422`, with a body describing the invalid parameter.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.