# Build your first app

> The minimum an app does to be installed, read a product and hear from the platform.

Source: https://developers-staging.foodpilot.tech/get-started/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](/build/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`:

```json
{
  "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**

```bash
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>
```

**Node.js**

```javascript
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();
```

**Python**

```python

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](/build/authentication) has the whole flow.

## 3. Read the installation, then a product

Ask the platform what you were granted:

**curl**

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

**Node.js**

```javascript
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
```

**Python**

```python
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:

```bash
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](/build/app-api) explains pagination, errors and the rate limit.

## 4. Verify the webhooks

Every webhook is signed with your `webhook_secret` and carries the same [envelope](/build/webhooks). Verify the signature on the raw body before you read it, and ignore an event id you have already handled.

## Next

- [Scopes](/build/scopes): what each scope lets you read.
- [App Bridge](/build/app-bridge): open your pages inside the platform.
- [Billing](/build/billing): sell your app.
