# App keys & token rotation

Use the publishable web key in browser code, and rotate your app token with a grace period for the old one.

## Two credentials

|                     | App token                                                                     | Publishable web key                                                                                                            |
| ------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Looks like          | 22 alphanumeric characters                                                    | `nnweb_…`                                                                                                                      |
| Can do              | **Everything** the app can: send, read inboxes, manage groups, read analytics | Register or deregister **one browser device**, and read or mark **that device's own inbox**. Reads the app's public VAPID key. |
| Can't do            | —                                                                             | Send, list groups or subscribers, read another device's data, or touch Classic or account routes                               |
| Safe in page source | **No**, it can send to everyone                                               | **Yes**                                                                                                                        |

Both go in the same place: wherever an endpoint takes `appToken` (the `:appToken` path parameter on GETs, the `appToken` body field on POSTs). The service tells them apart by the `nnweb_` prefix. A web key used outside the list below answers `403 web_key_not_allowed`. The app token keeps working everywhere.

> **Note:**
>
> Use the web key in every browser snippet, and keep the app token on your server and in native app builds.

## What a web key may call

| Call                  | Endpoint                                                                                                                   |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Register a web device | `POST /api/universal/device/register` with `{ appId, appToken: <webKey>, platform: "web", deviceId, webPush }`             |
| Deregister it         | `POST /api/universal/device/deregister` with `{ appId, appToken: <webKey>, deviceId }`                                     |
| List, unread count    | `GET /api/universal/inbox/:appId/:webKey?deviceId=…` and `…/unread-count?deviceId=…`                                       |
| Mark, delete          | `POST /api/universal/inbox/read`, `read-all`, `delete` or `clear` with `{ appId, appToken: <webKey>, deviceId, entryId? }` |
| Public VAPID key      | `GET /api/universal/web-push/keys/:appId/:webKey`                                                                          |

A web key reaches only these routes, and only devices it registered itself. A device registered with the app token, or on iOS or Android, is out of reach even if its `deviceId` is known (`403 web_key_scope`). A request on another app never matches (`401`, like a wrong token).

## Read the web key

```text
GET https://app.nativenotify.com/api/apps/<APP_ID>/web-key
```

This needs a Native Notify dashboard session or MCP token; an app token is refused on `/api/apps/*`. Like the VAPID keypair, the key is created the first time you read it.

```json
{
  "ok": true,
  "app": { "id": 123, "name": "Corner Bakery" },
  "webKey": "nnweb_1f1c…",
  "webKeyCreatedAt": "2026-09-29T12:00:00.000Z",
  "scope": { "canRegister": true, "canReadOwnDeviceInbox": true, "canSend": false },
  "webPush": { "tokenType": "web", "registerPath": "/api/universal/device/register", "maxPayloadBytes": 3993 }
}
```

In [Native Notify](https://dashboard.nativenotify.com), open your project's **Keys** page to copy or regenerate it (**Publishable web key**). The MCP tool is `get_app_web_key`.

## Rotate the web key

```text
POST https://app.nativenotify.com/api/apps/<APP_ID>/web-key/rotate    { "confirm": true }
```

The old key stops authenticating immediately, with no grace window. Owner or admin only; without `"confirm": true` the call answers `confirmation_required`. The MCP tool is `rotate_app_web_key`. In [Native Notify](https://dashboard.nativenotify.com), use **Regenerate** next to **Publishable web key** on your project's **Keys** page.

> **Sites set up by Agent Notify:**
>
> After rotating, update `NN_WEB_KEY` in `native-notify/web/nativeNotifyIds.js`, where Agent Notify puts the key, or ask Agent Notify to, and redeploy, or visitors can't register.

## Rotate the app token

Rotate after a leak. You choose how long the old token keeps working, so your own integration doesn't break.

```text
GET  /api/apps/<APP_ID>/app-token
POST /api/apps/<APP_ID>/app-token/rotate           { "confirm": true, "graceDays": 7 }
POST /api/apps/<APP_ID>/app-token/retire-previous  { "confirm": true }
```

- **Rotate** issues a new 22-character app token, valid immediately, and keeps the old one valid for `graceDays` (0–90, default 7; `0` retires it at once). It returns the new token and `previousToken: { activeUntil, graceDays }`, never the old value.
- **Get** returns the current token and `rotation: { previousTokenActive, previousTokenExpiresAt }`.
- **Retire** ends the grace window early. It's idempotent (`retired: false` when nothing was waiting). After the window, or a retire, the old token answers `401` like any unknown pair.
- A **second rotation** replaces the grace. Only one previous token exists, so the older one stops at once.
- Every mutation is audit-logged and owner or admin only (`403 admin_only` for a `developer` teammate).

The MCP tools are `get_app_token_status`, `rotate_app_token` and `retire_previous_app_token`. In [Native Notify](https://dashboard.nativenotify.com), open your project's **Keys** page and click **Rotate app token**.

Data tied to the token (devices, subscribers, Classic inboxes, scheduled pushes) follows the app to the new token. Update whatever authenticates with the old token, such as your app binary, server config or `.env`, before the grace window ends. Rotating leaves the web key, your devices and your inbox history alone.
