Skip to main content

Build your first app

In this page you will follow an app from its manifest to its first read of a product, and find the pages that detail each step.

Before you start​

  • A server with a public HTTPS address that you control.
  • An app registered in the marketplace, with its client_id and client_secret. The secret is shown once, when the app is registered.
  • A platform to test on, and an administrator of that platform who can install the app.

1. Write the manifest​

The manifest names your URLs and the scopes you need. A read-only app that shows the products of an organization needs read_products and read_organizations:

{
"manifest_version": 1,
"name": "Carbon report",
"handle": "carbon-report",
"install_url": "https://app.example.com/install",
"redirect_urls": ["https://app.example.com/oauth/callback"],
"scopes": ["read_products", "read_organizations"],
"webhooks": [{ "topic": "app/uninstalled", "uri": "https://app.example.com/webhooks" }]
}

Version 1 of the App API is read-only: the write_* scopes are refused when you submit the manifest.

2. Handle the install​

When an administrator clicks Install, the platform sends the browser to your install_url with ?platform=<platform name>. Redirect it to the platform's consent page, then exchange the code your redirect_url receives:

curl -X POST https://{tenant}-api.example.com/oauth/token \
-d grant_type=authorization_code \
-d client_id=carbon-report \
-d client_secret=<client_secret> \
-d code=<code> \
-d redirect_uri=https://app.example.com/oauth/callback \
-d code_verifier=<verifier>

The answer holds the access_token (a bearer token valid for an hour), a refresh_token, the granted scope and, only the first time, the webhook_secret. Keep all three. The authentication guide has the whole flow.

3. Read the installation, then a product​

Ask the platform what you were granted:

curl https://{tenant}-api.example.com/api/app/v1/installation \
-H "Authorization: Bearer <access_token>"

Then read a product of a granted organization:

curl https://{tenant}-api.example.com/api/app/v1/products/345 \
-H "Authorization: Bearer <access_token>"

A product outside the granted organizations answers 404, never 403: an app cannot learn what exists outside its grants. The App API guide explains pagination, errors and the rate limit.

4. Verify the webhooks​

Every webhook is signed with your webhook_secret and carries the same envelope. Verify the signature on the raw body before you read it, and ignore an event id you have already handled.

Next​