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_idandclient_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
- Node.js
- Python
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>
const response = await fetch('https://{tenant}-api.example.com/oauth/token', {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
body: new URLSearchParams({
grant_type: 'authorization_code',
client_id: process.env.CLIENT_ID,
client_secret: process.env.CLIENT_SECRET,
code,
redirect_uri: 'https://app.example.com/oauth/callback',
code_verifier: codeVerifier,
}),
});
const { access_token, refresh_token, scope, webhook_secret } = await response.json();
import os
import requests
response = requests.post(
"https://{tenant}-api.example.com/oauth/token",
data={
"grant_type": "authorization_code",
"client_id": os.environ["CLIENT_ID"],
"client_secret": os.environ["CLIENT_SECRET"],
"code": code,
"redirect_uri": "https://app.example.com/oauth/callback",
"code_verifier": code_verifier,
},
headers={"Accept": "application/json"},
timeout=10,
)
response.raise_for_status()
tokens = response.json() # access_token, refresh_token, scope, webhook_secret (first activation only)
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
- Node.js
- Python
curl https://{tenant}-api.example.com/api/app/v1/installation \
-H "Authorization: Bearer <access_token>"
const installation = await fetch('https://{tenant}-api.example.com/api/app/v1/installation', {
headers: { Authorization: `Bearer ${accessToken}`, Accept: 'application/json' },
}).then((r) => r.json());
// installation.grantedScopes, installation.organizationIds
installation = requests.get(
"https://{tenant}-api.example.com/api/app/v1/installation",
headers={"Authorization": f"Bearer {access_token}", "Accept": "application/json"},
timeout=10,
).json()
# installation["grantedScopes"], installation["organizationIds"]
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
- Scopes: what each scope lets you read.
- App Bridge: open your pages inside the platform.
- Billing: sell your app.