> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Read App Settings

> Read the saved settings of an installation with an app access token. Covers the scope, the response fields, action_needed, and invalid_keys.

> [!WARNING]
>
> App settings are in development. They are not yet available in production, and details can change before release.

## Request

Call this endpoint with the access token of the installation. Dodo Payments finds the installation from the token, so the request has no installation ID. Use the API host of the installation: `https://test.dodopayments.com` for a test install or `https://live.dodopayments.com` for a live install.

> [!NOTE]
>
> The token needs the `app_settings:read` scope. Dodo Payments adds this scope to the access tokens of your app. You do not request it. A token without the scope gets a `403` response.

```bash cURL theme={null}
curl https://test.dodopayments.com/app-installation/settings \
  -H "Authorization: Bearer $APP_ACCESS_TOKEN"
```

```javascript Node.js theme={null}
const res = await fetch('https://test.dodopayments.com/app-installation/settings', {
  headers: { Authorization: `Bearer ${process.env.APP_ACCESS_TOKEN}` },
});
const settings = await res.json();
```

## Response

```json theme={null}
{
  "installation_id": "ains_123",
  "app_id": "app_123",
  "manifest_version": 1,
  "live_manifest_version": 2,
  "values": {
    "project_name": "Acme",
    "sample_rate": 50,
    "region": "eu",
    "events": ["payment.succeeded", "refund.succeeded"]
  },
  "secrets": {
    "api_key": "sk_live_example"
  },
  "action_needed": true,
  "invalid_keys": ["sample_rate"],
  "updated_at": "2026-11-12T10:30:00Z"
}
```

**installation\_id** `string`

The installation of the token.

**app\_id** `string`

Your app.

**manifest\_version** `integer | null`

The manifest version of the last save. It is `null` if the merchant never saved settings.

**live\_manifest\_version** `integer`

The version that is live now. If `manifest_version` is lower, the merchant has not yet seen the newest fields.

**values** `object`

The values of the non-secret fields, by key. It is `{}` if nothing is saved. Only keys of the live manifest are included.

**secrets** `object`

The values of the `secret` fields, by key. It is `{}` if nothing is saved. Do not log these values.

**action\_needed** `boolean`

`true` if a required field has no value, or a stored value fails a rule of the live manifest.

**invalid\_keys** `string[]`

The keys of stored values that fail a rule of the live manifest.

**updated\_at** `string | null`

The time of the last save. It is `null` if nothing is saved.

### No saved settings

If the merchant has not saved settings, you get a normal `200` response:

```json theme={null}
{
  "installation_id": "ains_123",
  "app_id": "app_123",
  "manifest_version": null,
  "live_manifest_version": 1,
  "values": {},
  "secrets": {},
  "action_needed": true,
  "invalid_keys": [],
  "updated_at": null
}
```

`action_needed` is `true` here only if the manifest has a required field.

## Handle action\_needed

An installation with `action_needed` set to `true` is still active. Dodo Payments does not block it. Your app decides what to do. For example, stop sync jobs until the merchant finishes the setup, and use `invalid_keys` to tell the merchant which fields to fix.

## Errors

| Status | Cause |
| - | - |
| `401` | The token is not valid, or the installation is not active. |
| `403` | The token has no `app_settings:read` scope. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.