# Positive Apps > Build apps for the Positive marketplace. Guides for the publishers of apps: install with OAuth, read the App API, receive webhooks, embed pages with App Bridge, sell plans. Essentials an agent must not get wrong: - Each customer platform has its own API host; examples write it `https://{tenant}-api.example.com`. Never hard-code one. - The App API (`/api/app/v1`) is read-only in version 1; `write_*` scopes are refused. - Verify every webhook signature (`X-Positive-Signature-V2` = `v1=` + base64 HMAC-SHA256 of `timestamp + "." + rawBody`, with the installation's webhook secret) on the raw body before parsing, and deduplicate by event id. - Access tokens live one hour; refresh tokens rotate on every use (store the new one). Session tokens of embedded pages live 60 seconds: verify them on your server. - A resource outside the installation's organizations answers 404, by design. ## Start here - [App template](https://github.com/Foodpilot/positive-app-template): a working app (Node.js, TypeScript) to start from; its AGENTS.md lists the rules for coding agents - [@foodpilot/app-bridge](https://www.npmjs.com/package/@foodpilot/app-bridge): the SDK for embedded pages and session-token verification ## Guides - [Overview](https://developers-staging.foodpilot.tech/get-started/overview.md): What an app on the Positive marketplace can do, and where to start. - [Run the sample app](https://developers-staging.foodpilot.tech/get-started/sample-app.md): Start from a working app that installs with OAuth, verifies webhooks, and opens an embedded page and two extension slots. - [Build your first app](https://developers-staging.foodpilot.tech/get-started/first-app.md): The minimum an app does to be installed, read a product and hear from the platform. - [Add a tab to the product page](https://developers-staging.foodpilot.tech/tutorials/product-tab.md): Show your app's view of a product inside the platform's product page, with the product chosen by the platform and verified on your server. - [React when scores change](https://developers-staging.foodpilot.tech/tutorials/react-to-scores.md): Receive scores/updated, verify it, handle each event once, and keep your copy of a product's scores up to date. - [Sell a plan](https://developers-staging.foodpilot.tech/tutorials/sell-a-plan.md): Let an administrator subscribe to your plan from your embedded page, confirm it in the platform, and unlock your features from the subscription status. - [Install, tokens and session tokens](https://developers-staging.foodpilot.tech/build/authentication.md): How an app is installed with OAuth, how it gets and refreshes its tokens, and how it recognizes the user in an embedded page. - [Scopes](https://developers-staging.foodpilot.tech/build/scopes.md): What each scope lets an app read in version 1, how scopes combine with organizations, and why the write scopes are not available yet. - [The manifest](https://developers-staging.foodpilot.tech/build/manifest.md): Every field of the app manifest, version 1, with its rules. - [App API](https://developers-staging.foodpilot.tech/build/app-api.md): The API an installed app calls: authentication, organizations, pagination, errors and the rate limit. - [Versioning and deprecation](https://developers-staging.foodpilot.tech/build/app-api/versioning.md): What version 1 may and may not change, and how long a version is kept once the next one ships. - [Webhooks](https://developers-staging.foodpilot.tech/build/webhooks.md): The v1 envelope every webhook uses, its headers, the delivery rules and how failed deliveries are retried and redelivered. - [Topics](https://developers-staging.foodpilot.tech/build/webhooks/topics.md): The six webhook topics of version 1, the scope each needs, and the data each one carries. - [Verify signatures](https://developers-staging.foodpilot.tech/build/webhooks/verify-signatures.md): How to check that a webhook comes from the platform and is not a replay, with samples in Node.js and Python. - [App Bridge](https://developers-staging.foodpilot.tech/build/app-bridge.md): How an embedded app talks to the platform page that frames it: session tokens, toast, confirm, navigation, title and loading. - [Extension slots](https://developers-staging.foodpilot.tech/build/extension-slots.md): The places inside the platform where an app can add a tab or a card, how to declare them, and how they differ from a full page. - [Billing](https://developers-staging.foodpilot.tech/build/billing.md): How an app sells itself: plans, a subscription or a one-time charge, the customer's confirmation, and the webhooks that tell you the status. - [Test your app](https://developers-staging.foodpilot.tech/launch/testing.md): How to install your app on a test platform before it is listed, and what to check before you submit it to everyone. - [The review](https://developers-staging.foodpilot.tech/launch/review.md): What happens when you submit a version, the automated checks and what each verifies, the reasons for a rejection, and how a release reaches installed apps. - [Your listing](https://developers-staging.foodpilot.tech/launch/listing.md): The texts, categories, links, logo and screenshots of your app's page in the marketplace, and their limits. - [Design guidelines](https://developers-staging.foodpilot.tech/launch/design.md): How an embedded page and an extension should look and behave inside the platform, from the platform's constraints to our recommendations. - [Security and privacy](https://developers-staging.foodpilot.tech/launch/security-privacy.md): The rules your URLs, secrets, embedded pages and stored data must follow, and what you owe a customer when your app is uninstalled. - [App Bridge SDK](https://developers-staging.foodpilot.tech/sdk/app-bridge.md): Every function, option, limit and error of @foodpilot/app-bridge, for the browser and for your server. - [Scopes](https://developers-staging.foodpilot.tech/reference/scopes.md): Every scope an app can name in its manifest, and whether version 1 grants it. - [Manifest schema](https://developers-staging.foodpilot.tech/reference/manifest-schema.md): Every field of manifest version 1 and its constraints, from the JSON Schema the platform validates against. - [Webhook events](https://developers-staging.foodpilot.tech/reference/webhook-events.md): The payload of every webhook topic, from the JSON Schemas the platform's deliveries follow. - [Extension slots](https://developers-staging.foodpilot.tech/reference/extension-slots.md): Every place in the platform where an app can show a frame, with its size and the context it receives. - [Errors](https://developers-staging.foodpilot.tech/errors.md): Every error of the App API, with its type URI, its status and what to do about it. - [Changelog](https://developers-staging.foodpilot.tech/resources/changelog.md): Changes to the App API, the manifest, webhooks and App Bridge, newest first. - [Glossary](https://developers-staging.foodpilot.tech/resources/glossary.md): The words of the platform and of the marketplace, as these guides use them. ## Machine-readable contract - [App API, OpenAPI 3.0](https://developers-staging.foodpilot.tech/openapi-3.0.json): every operation of the App API - [Manifest v1 (JSON Schema)](https://developers-staging.foodpilot.tech/schemas/manifest.v1.schema.json) - [Scopes](https://developers-staging.foodpilot.tech/schemas/scopes.json) - [Extension slots](https://developers-staging.foodpilot.tech/schemas/slots.json) - [Errors (type URI, status, meaning, remedy)](https://developers-staging.foodpilot.tech/schemas/errors.json) - [Webhook payload app/scopes_updated](https://developers-staging.foodpilot.tech/schemas/webhooks/app.scopes_updated.schema.json) - [Webhook payload app/uninstalled](https://developers-staging.foodpilot.tech/schemas/webhooks/app.uninstalled.schema.json) - [Webhook payload app_charge/updated](https://developers-staging.foodpilot.tech/schemas/webhooks/app_charge.updated.schema.json) - [Webhook payload app_subscription/updated](https://developers-staging.foodpilot.tech/schemas/webhooks/app_subscription.updated.schema.json) - [Webhook payload questionnaires/answered](https://developers-staging.foodpilot.tech/schemas/webhooks/questionnaires.answered.schema.json) - [Webhook payload scores/updated](https://developers-staging.foodpilot.tech/schemas/webhooks/scores.updated.schema.json) ## Optional - [All guides in one file](https://developers-staging.foodpilot.tech/llms-full.txt)