Overview
An app for the Positive marketplace is a web service you run. A customer platform installs it, chooses which organizations it may see and which data it may read, and the platform then talks to your app in three ways. This site documents all three, and nothing else: only what an app may rely on.
What an app uses
| What | What it is | Read |
|---|---|---|
| The App API | The only HTTP API an installed app can call, under /api/app/v1. Read-only in version 1. | App API and the API reference |
| Webhooks | The platform calls your HTTPS endpoint when something happens: scores computed, a questionnaire answered, the app uninstalled, a payment changed. | Webhooks |
| Embedding | Your pages open inside the platform, as a full page, a product tab or an overview card, and learn who is there from a signed session token. | App Bridge and Extension slots |
The path of an app
- Describe it in a manifest: its URLs, the scopes it asks for, the webhooks and the pages it wants.
- Let customers install it. The OAuth flow gives your server an installation token, a refresh token and the secret that signs webhooks.
- Read the customer's data with the App API, within the granted scopes and organizations.
- Listen with webhooks and show your pages with App Bridge.
- Charge for it, if you want to, with billing.
Good to know
- One host per platform. Every customer platform has its own API host. The examples use
https://{tenant}-api.example.com: use the host your installation was made on. - An app token only reaches the App API. The installation token is refused everywhere else, whatever the scopes. The data an app may see is exactly what this site documents.
- Version 1 only gets additive changes. A new field or a new operation can appear at any time: ignore what you do not know. Anything else is a version 2 on a new path, with 12 months of overlap.
- The reference is the contract. The API reference is generated from the committed OpenAPI document, which you can download to generate a client.