The manifest
In this page you will find every field of the manifest, the rules each one is checked against, and a complete example.
Example
{
"manifest_version": 1,
"name": "Carbon report",
"handle": "carbon-report",
"install_url": "https://app.example.com/install",
"app_url": "https://app.example.com/app",
"redirect_urls": ["https://app.example.com/oauth/callback"],
"scopes": ["read_products", "read_organizations"],
"embedded": true,
"navigation": [
{ "label": { "en": "Home", "fr": "Accueil" }, "path": "/app" },
{ "label": { "en": "Reports", "fr": "Rapports" }, "path": "/app/reports" }
],
"extensions": [
{ "slot": "product.details.tab", "path": "/app/extensions/product", "label": { "en": "Carbon", "fr": "Carbone" } }
],
"support_url": "https://app.example.com/support",
"privacy_url": "https://app.example.com/privacy",
"webhooks": [
{ "topic": "scores/updated", "uri": "https://app.example.com/webhooks" },
{ "topic": "app/uninstalled", "uri": "https://app.example.com/webhooks" }
]
}
Fields
| Field | Required | Rules |
|---|---|---|
manifest_version | yes | 1 |
name | yes | 1 to 100 characters |
handle | yes | Lowercase letters, digits and single hyphens, at most 64. It is the path of your app in the platform: /apps/<handle> |
install_url | yes | Where the platform sends an administrator to install |
redirect_urls | yes | 1 to 10 distinct URLs your OAuth callback may use, compared exactly |
scopes | yes | Distinct scopes. write_* scopes are refused in version 1 |
app_url | with embedded | The page the platform frames |
embedded | no | true to open the app inside the platform. Requires app_url |
navigation | no | Up to 10 tabs of the embedded page. Requires embedded |
extensions | no | Up to 10 places the app adds content to: see extension slots. Requires embedded |
support_url, privacy_url | no | Shown on the app's page in the marketplace |
webhooks | no | Up to 20 {topic, uri}: see webhooks |
URLs. Every URL is absolute https (http only for a loopback host while you develop), with no fragment, no wildcard and no credentials. A webhook uri is always https, and is checked again at delivery: an address that resolves to a private or loopback network is refused.
Paths in navigation and extensions start with /, stay under the path of your app_url, and cannot contain .., encoded slashes or backslashes. Entries that fail are dropped.
Labels are { "en": "...", "fr": "..." }: en is required, fr optional, 1 to 40 characters each.
Webhook topics are the ones of the catalog. A topic whose scope you did not request is not subscribed.
Updating the manifest
A new release that adds no scope and no new destination (an origin of app_url, install_url, redirect_urls or a webhook uri, or embedding turned on) is applied to installed apps automatically. Any other release waits for the administrator to consent again, and the installation shows an update is available.