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

# App manifest

> Define your whole OAuth app, from details and permissions to buttons, panels, navigation and events, as one JSON document

A **manifest** is your app's complete definition as one JSON document: its details and permissions, allowed domains, [buttons, panels, navigation, and event subscriptions](https://docs.campfire.ai/guides/app-extensions.md). Keep it in your repository next to your code, review changes like any other change, and apply it to Campfire in one step.

> [card] [FakeTax manifest.json](https://github.com/Campfire-eng/campfire_faketax_app/blob/main/manifest.json)
>
> The sample app's manifest: five buttons, two panels, a sidebar section, and event subscriptions.

> [card] [Extending Campfire](https://docs.campfire.ai/guides/app-extensions.md)
>
> What each extension does and how your server handles it.

## Applying a manifest

### Creating a new app

On [Settings > Developer > Apps](https://app.meetcampfire.com/v2/settings/apps), click **From Manifest** (or **Create from Manifest** if you have no apps yet), paste your manifest, and click **Create App**.

![The Create app from manifest dialog with a JSON text area](https://mintcdn.com/campfire/EZaYuU9NXAcXYXMc/images/oauth-apps/from-manifest-dialog.png?fit=max\&auto=format\&n=EZaYuU9NXAcXYXMc\&q=85\&s=eba37fdd4f8771efb3d0d703804eed9f)

The `app` section becomes **version 1** in production straight away, and the extensions are created with it. Campfire then shows the client secret once, as when you [create an app by hand](https://docs.campfire.ai/guides/oauth-apps.md#part-1-register-your-app). `app.allowed_scopes` is required when creating from a manifest. Use `[]` for an app with no permissions.

### Updating an existing app

Open the app's **Manifest** tab. It shows the app's current manifest, which you can copy into your repository. Paste the new version and click **Save Manifest**.

![The Manifest tab showing FakeTax's manifest as JSON with a Save Manifest button](https://mintcdn.com/campfire/EZaYuU9NXAcXYXMc/images/oauth-apps/app-manifest.png?fit=max\&auto=format\&n=EZaYuU9NXAcXYXMc\&q=85\&s=c16198e9eff3e9905cdb3a5747b8abcb)

Saving is **all or nothing**. If any part is invalid, nothing changes and you get an error naming the part (see [Errors](#errors)). When it succeeds:

* **The `app` section is versioned.** Fields that differ from the version you're editing go to the app's development version, which goes live only when you [promote it](https://docs.campfire.ai/guides/oauth-apps.md#versions-and-approval). If nothing in `app` changed, no draft is opened.
* **Everything else takes effect immediately**, in every workspace where your app is connected: allowed domains, buttons, panels, navigation, event subscriptions and hooks.
* **The manifest is the full list.** Buttons, panels, and navigation entries are matched by `key`, and subscriptions and hooks by `endpoint_url`. Anything that isn't in the manifest is **deleted**.
* **Workspace settings survive.** Because items are matched by key, a workspace admin's switches and style choices stay in place when you re-apply. Changing a key creates a new item, which loses them.
* **Allowed domains are applied first**, so one manifest can add a domain and the button that uses it.

> [!WARNING]
>
> Leaving out `slots`, `panels`, `navigation`, `event_subscriptions` or `hooks` is the same as sending an empty list: everything in that section is deleted. Leaving out `app` or `allowed_domains` leaves them unchanged.

### Over the API

The same operations are available to a workspace admin's session at `https://api.meetcampfire.com`:

| Method and path | Does |
| - | - |
| `GET /ca/api/v1/oauth-apps/<app_id>/manifest` | Export the manifest. The `app` section shows the development version if there is one. |
| `PUT /ca/api/v1/oauth-apps/<app_id>/manifest` | Apply a manifest. Returns the manifest as saved. |
| `POST /ca/api/v1/oauth-apps/from-manifest` | Create an app. Returns the app, its `client_secret` (shown once), and its `manifest`. |
| `GET /ca/api/v1/oauth-apps/extension-catalog` | Object types, the fields each can test in `visible_when`, and the event topics. |

> [!NOTE]
>
> App management endpoints are never available to OAuth app tokens.

## Reference

A manifest is a JSON object with up to seven sections:

```json theme={null}
{
  "app": { },
  "allowed_domains": [],
  "slots": [],
  "panels": [],
  "navigation": [],
  "event_subscriptions": [],
  "hooks": []
}
```

### `app`

The app's versioned details. Only these keys are allowed:

| Key | Type | Notes |
| - | - | - |
| `name` | string | Required. |
| `tagline` | string | Up to 120 characters. |
| `category` | string | Where the app is listed on the Connections page: `ap`, `ar`, `banking`, `crm`, `data_upload`, `payroll`, `tax`, or `""` for the generic **Apps** section. |
| `description` | string | Up to 2,000 characters. |
| `icon_url` | string or `null` | Must be an icon already uploaded to Campfire. Upload one on the **Details** tab, then export to get its URL. |
| `redirect_uris` | string\[] | Up to 20. See [redirect URL rules](https://docs.campfire.ai/guides/oauth-apps.md#part-1-register-your-app). |
| `connect_url` | string | Where **Connect** on the connection page sends people. |
| `manage_url` | string | Where **Manage in \<App>** sends people. See [Manage URL](https://docs.campfire.ai/guides/app-extensions.md#manage-url). |
| `allowed_scopes` | string\[] | The app's permission ceiling, using [scope names](https://docs.campfire.ai/guides/oauth-apps.md#scopes-reference) such as `invoices:write`. Add `openid`, `email` and `profile` for [Sign in with Campfire](https://docs.campfire.ai/guides/oauth-apps.md#sign-in-with-campfire-openid-connect). |

### `allowed_domains`

Up to 20 host names. `example.com` matches only that host. `*.example.com` matches its subdomains, but not `example.com`. Every URL in the sections below must be on one of these hosts.

### `slots` (buttons)

| Key | Type | Notes |
| - | - | - |
| `key` | string | Unique within the app. Up to 64 characters, slug format. |
| `label` | string | Up to 60 characters. |
| `icon` | string | A [Lucide](https://lucide.dev/icons) icon name, for example `calculator`. |
| `object_type` | string | `invoice`, `bill`, `journal_entry`, or `vendor`. |
| `surface` | string | `detail_header`, `list_header`, or `row_menu`. |
| `requested_variant` | string | `menu` (default), `secondary`, or `primary`. |
| `action_type` | string | `link`, `webhook`, or `iframe`. |
| `action_config` | object | Depends on `action_type`. See below. |
| `visible_when` | object\[] | Up to 5 rules: `{"field", "op", "value"}`, with `op` one of `eq`, `neq`, `in`, `not_in`. |
| `confirm_text` | string | Up to 200 characters. Empty for no confirmation. |
| `order` | integer | Sort order within the same placement. |
| `is_active` | boolean | `false` hides the button everywhere. Must be a real boolean. |

`action_config` by action type:

| `action_type` | `action_config` |
| - | - |
| `link` | `{"url_template"}` |
| `webhook` | `{"url_template", "timeout_ms"}`. `timeout_ms` is 1000 to 10000 (default 8000). |
| `iframe` | `{"url_template", "presentation", "width"}`. `presentation` is `drawer` (default) or `modal`. `width` is `sm`, `md` (default), or `lg`. |

URL templates can be up to 1,024 characters and use `{{record.id}}`, `{{record.number}}`, `{{customer.id}}`, and `{{install.<key>}}`. `{{record.*}}` isn't allowed on `list_header`.

### `panels`

| Key | Type | Notes |
| - | - | - |
| `key` | string | Unique within the app. |
| `label` | string | The tab title. Up to 60 characters. |
| `icon` | string | Lucide icon name. |
| `object_type` | string | `invoice`, `bill`, `journal_entry`, or `vendor`. |
| `placements` | string\[] | One or more of `list`, `detail`, `edit`. |
| `url_template` | string | `{{record.*}}` isn't allowed when `list` is a placement. |
| `visible_when` | object\[] | As for buttons. |
| `order` | integer | Sort order. |
| `is_active` | boolean | |

### `navigation`

A list of top-level entries. Each entry can hold one level of `items`:

| Key | Type | Notes |
| - | - | - |
| `key` | string | Unique across all entries and items. |
| `label` | string | Up to 40 characters. |
| `icon` | string | Lucide icon name. Top-level entries only: an icon on an item is ignored. |
| `url_template` | string | Empty for a section that only groups items. Required on items. Only `{{customer.*}}` and `{{install.*}}`. |
| `order` | integer | Optional. Defaults to the entry's position in the list. |
| `is_active` | boolean | |
| `items` | object\[] | Top-level entries only. Items have the same keys, without `items`. |

At most 30 entries in total, counting items.

### `event_subscriptions`

| Key | Type | Notes |
| - | - | - |
| `endpoint_url` | string | Where events are posted. Only `{{customer.*}}` and `{{install.*}}`. Identifies the subscription when you re-apply. |
| `topics` | string\[] | Non-empty. Each must be covered by `app.allowed_scopes`. See [topics](https://docs.campfire.ai/guides/app-extensions.md#event-subscriptions). |
| `is_active` | boolean | |

### `hooks`

Available to [preferred partners](https://docs.campfire.ai/guides/app-extensions.md#hooks) only. A manifest with a non-empty `hooks` list is refused for other apps.

| Key | Type | Notes |
| - | - | - |
| `endpoint_url` | string | Where hook calls are posted. Only `{{customer.*}}` and `{{install.*}}`. Identifies the hook when you re-apply. |
| `topics` | string\[] | Non-empty. Each must be covered by `app.allowed_scopes` at the write tier. See [topics](https://docs.campfire.ai/guides/app-extensions.md#hooks). |
| `on_failure` | string | `proceed` (default) or `block`. |
| `preview_label` | string | Up to 40 characters. When set, the hook gets a [button](https://docs.campfire.ai/guides/app-extensions.md#the-preview-button) on create and edit forms. |
| `is_active` | boolean | |

## Errors

Saving an invalid manifest returns `400` with a `detail` that says where the problem is:

| Example `detail` | Fix |
| - | - |
| `app: not part of the manifest: client_id` | Remove keys that aren't listed under [`app`](#app). |
| `slots[2]: visible_when: payment_status cannot be tested on vendor; use country, is_1099, vendor_type` | Use a field from the [visibility table](https://docs.campfire.ai/guides/app-extensions.md#visibility-rules). |
| `Slot keys must be unique.` | Give every button its own `key`. Panels and navigation work the same way. |
| `Too many slots, panels, navigation entries, subscriptions or hooks.` | Stay within the [limits](https://docs.campfire.ai/guides/app-extensions.md#limits). |
| `slots, panels, navigation, event_subscriptions and hooks must be lists.` | Use `[]`, not `{}` or `null`. |
| `hooks[0]: Hooks are available to Campfire partners by invitation.` | Remove the `hooks` section, or contact your Campfire support team. |
| `allowed_domains: ...` | Fix the host name. |

A URL that isn't on an allowed domain, a topic your scopes don't cover, or a `{{record.*}}` placeholder where it isn't allowed is reported against the item it's in.

## Example: FakeTax

This is FakeTax's complete [`manifest.json`](https://github.com/Campfire-eng/campfire_faketax_app/blob/main/manifest.json). It runs on `localhost`, so every URL uses `http://localhost:3999`. In production, use your own `https` host.

> [accordion] manifest.json
>
> ```json manifest.json theme={null}
> {
>   "app": {
>     "name": "FakeTax",
>     "tagline": "Made-up sales tax on invoices",
>     "category": "tax",
>     "description": "Sales tax for invoices and credit memos by jurisdiction, with tax codes on lines. The tax is fake; the plumbing is real.",
>     "icon_url": null,
>     "redirect_uris": [
>       "http://localhost:3999/callback"
>     ],
>     "connect_url": "http://localhost:3999/connect",
>     "allowed_scopes": [
>       "invoices:read",
>       "invoices:write",
>       "credit_memos:write",
>       "custom_fields:write",
>       "vendors:read",
>       "tax_rates:write",
>       "accounts:write"
>     ],
>     "manage_url": "http://localhost:3999/manage"
>   },
>   "allowed_domains": [
>     "localhost"
>   ],
>   "slots": [
>     {
>       "key": "view",
>       "label": "View in FakeTax",
>       "icon": "external-link",
>       "object_type": "invoice",
>       "surface": "detail_header",
>       "requested_variant": "menu",
>       "action_type": "link",
>       "action_config": {
>         "url_template": "http://localhost:3999/report/{{record.id}}"
>       },
>       "visible_when": [],
>       "confirm_text": "",
>       "order": 2,
>       "is_active": true
>     },
>     {
>       "key": "calculate",
>       "label": "Calculate tax",
>       "icon": "calculator",
>       "object_type": "invoice",
>       "surface": "detail_header",
>       "requested_variant": "secondary",
>       "action_type": "webhook",
>       "action_config": {
>         "url_template": "http://localhost:3999/slots/calculate",
>         "timeout_ms": 8000
>       },
>       "visible_when": [
>         {
>           "field": "payment_status",
>           "op": "in",
>           "value": [
>             "draft",
>             "open"
>           ]
>         }
>       ],
>       "confirm_text": "Overwrite tax on every line?",
>       "order": 0,
>       "is_active": true
>     },
>     {
>       "key": "calculate-bulk",
>       "label": "Calculate FakeTax",
>       "icon": "calculator",
>       "object_type": "invoice",
>       "surface": "list_header",
>       "requested_variant": "menu",
>       "action_type": "webhook",
>       "action_config": {
>         "url_template": "http://localhost:3999/slots/calculate",
>         "timeout_ms": 8000
>       },
>       "visible_when": [],
>       "confirm_text": "",
>       "order": 0,
>       "is_active": true
>     },
>     {
>       "key": "open-row",
>       "label": "FakeTax report",
>       "icon": "external-link",
>       "object_type": "invoice",
>       "surface": "row_menu",
>       "requested_variant": "menu",
>       "action_type": "link",
>       "action_config": {
>         "url_template": "http://localhost:3999/report/{{record.id}}"
>       },
>       "visible_when": [],
>       "confirm_text": "",
>       "order": 0,
>       "is_active": true
>     },
>     {
>       "key": "breakdown",
>       "label": "Tax breakdown",
>       "icon": "table",
>       "object_type": "invoice",
>       "surface": "detail_header",
>       "requested_variant": "menu",
>       "action_type": "iframe",
>       "action_config": {
>         "url_template": "http://localhost:3999/frame/breakdown/{{record.id}}",
>         "presentation": "drawer",
>         "width": "lg"
>       },
>       "visible_when": [],
>       "confirm_text": "",
>       "order": 1,
>       "is_active": true
>     }
>   ],
>   "panels": [
>     {
>       "key": "breakdown-tab",
>       "label": "FakeTax",
>       "icon": "table",
>       "object_type": "invoice",
>       "placements": [
>         "detail",
>         "edit"
>       ],
>       "url_template": "http://localhost:3999/frame/breakdown/{{record.id}}",
>       "visible_when": [],
>       "order": 0,
>       "is_active": true
>     },
>     {
>       "key": "settings",
>       "label": "FakeTax",
>       "icon": "settings",
>       "object_type": "invoice",
>       "placements": [
>         "list"
>       ],
>       "url_template": "http://localhost:3999/frame/settings",
>       "visible_when": [],
>       "order": 0,
>       "is_active": true
>     }
>   ],
>   "navigation": [
>     {
>       "key": "faketax",
>       "label": "FakeTax",
>       "icon": "calculator",
>       "url_template": "",
>       "is_active": true,
>       "items": [
>         {
>           "key": "jurisdictions",
>           "label": "Jurisdictions",
>           "url_template": "http://localhost:3999/frame/manage",
>           "is_active": true
>         },
>         {
>           "key": "tax-codes",
>           "label": "Tax codes",
>           "url_template": "http://localhost:3999/frame/codes",
>           "is_active": true
>         },
>         {
>           "key": "settings",
>           "label": "Settings",
>           "url_template": "http://localhost:3999/frame/settings",
>           "is_active": true
>         }
>       ]
>     }
>   ],
>   "event_subscriptions": [
>     {
>       "topics": [
>         "Invoice.created",
>         "Invoice.updated",
>         "Invoice.deleted",
>         "CreditMemo.created",
>         "CreditMemo.updated"
>       ],
>       "endpoint_url": "http://localhost:3999/events",
>       "is_active": true
>     }
>   ],
>   "hooks": [
>     {
>       "topics": [
>         "Invoice.create",
>         "Invoice.update"
>       ],
>       "endpoint_url": "http://localhost:3999/hooks",
>       "on_failure": "proceed",
>       "preview_label": "Preview FakeTax",
>       "is_active": true
>     }
>   ]
> }
> ```

It defines:

* **Five buttons** on invoices: **Calculate tax** (a secondary webhook button on draft and open invoices, with a confirmation), **Calculate FakeTax** (the same webhook for selected rows on the list), **Tax breakdown** (a large drawer), **View in FakeTax** (a link), and **FakeTax report** (a link in the row menu).
* **Two panels**: the breakdown on the invoice page and edit modal, and settings on the invoice list.
* **A sidebar section** with three pages.
* **One subscription** for invoice and credit memo changes.
