# Managing apps

App creation, the settings fields, API key semantics, deletion.

Other guides: [quickstart.md](quickstart.md) · [events.md](events.md) · [revenuecat.md](revenuecat.md) · [agent-api.md](agent-api.md) · [apple-ads.md](apple-ads.md)

## Add an app

`https://activationpal.com/dashboard/apps/new` (standalone first-run page), or dashboard → gear icon → app dropdown → **All apps** → add apps. Creation returns:

- **id (slug)** — from the name, lowercase letters and digits only (`My App` → `myapp`; numeric suffix if taken). The `app` value in `ActivationPal.configure` and the agent API.
- **API key** (`ap_pk_...`) — shown exactly once; see below.

## Bulk add

`https://activationpal.com/dashboard/apps/new?bulk=1` (or the **bulk** tab of the add-apps form) — one line per app, up to 50 per submit:

```
App Name, com.bundle.id[, appstore-id]
```

App Store id optional. The picked timezone applies to the whole batch (each app changeable later). Each created app returns its own API key; a bad line fails alone.

## Settings

Dashboard → gear icon. The dropdown holds every app plus **All apps**: an app shows its settings, All apps the roster (multi-select delete, inline add).

| Field | Required | Effect |
|---|---|---|
| App name | yes (min 2 chars) | Display name. Changing it does NOT change the app's id. |
| Bundle ID | yes | Reverse-DNS id from Xcode (`com.company.myapp`). Matches events to this app; fetches the App Store icon. |
| App Store ID | no | The number in `apps.apple.com/…/id<THIS>`. Only needed for the Apple Ads card — add it once the app ships. |
| Timezone | yes | IANA zone. Every chart bucket and daily cut — dashboard and `get_stats` — runs in it; "today" means today in this zone. Events are stored in UTC, so changing it re-buckets history losslessly. |

## API key

- `ap_pk_` + 48 hex chars. Stored as a SHA-256 hash — cannot be read back, by anyone. Save it when shown.
- Used in two places: the SDK sends it as the `x-app-key` header on ingest (you pass it to `configure`); the RevenueCat webhook sends it as the `Authorization` header ([revenuecat.md](revenuecat.md)).
- Rotation (settings → rotate key): new key shown once; the old one stops the same moment — update `configure` and the webhook immediately. Events sent with the old key are rejected with 401; the SDK keeps them buffered on-device and delivers them once a build with the new key runs.
- Not an agent API key — those are `ap_sk_`, minted in the **agent api** tab ([agent-api.md](agent-api.md)).

## Webhook URL

`https://activationpal.com/api/rc` — same URL for every app; the app's API key in the Authorization header identifies the app. Setup: [revenuecat.md](revenuecat.md).

## Deleting an app

Delete (in settings) removes the app **and every event it ever recorded** — irreversible: no soft delete, no export, no recovery. Its API key and webhook stop working with it. To keep the history, leave the app; one that no longer sends events costs nothing.