Apps

Create and manage push notification apps. Each app has its own VAPID keypair, subscriber base, and notification settings.

Base URL: https://app.krafter.dev/api/v1

List Apps

Retrieve all push apps for your account.

GET /push/apps

Required scope: push:read

Example Request

curl https://app.krafter.dev/api/v1/push/apps \
  -H "Authorization: Bearer kr_live_abc123def456"

Example Response

{
  "data": [
    {
      "id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "name": "My Production App",
      "vapid_public_key": "BNbx...",
      "subscriber_count": 12450,
      "settings": {
        "default_icon": "https://example.com/icon.png",
        "default_url": "https://example.com"
      },
      "created_at": "2025-06-01T08:00:00Z",
      "updated_at": "2025-06-10T14:30:00Z"
    },
    {
      "id": "b2c3d4e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
      "name": "Staging App",
      "vapid_public_key": "BKcx...",
      "subscriber_count": 340,
      "settings": {},
      "created_at": "2025-06-05T10:00:00Z",
      "updated_at": "2025-06-05T10:00:00Z"
    }
  ]
}

---

Create App

Create a new push app. A VAPID keypair is automatically generated. The private key is included in the response and shown only once.

POST /push/apps

Required scope: push:write

Request Body

Field	Type	Required	Description
name	string	Yes	Display name for the app.
settings	object	No	Default notification settings (e.g., default_icon, default_url).

Example Request

curl -X POST https://app.krafter.dev/api/v1/push/apps \
  -H "Authorization: Bearer kr_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Production App",
    "settings": {
      "default_icon": "https://example.com/icon.png",
      "default_url": "https://example.com"
    }
  }'

Example Response

// 201 Created
{
  "data": {
    "id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "name": "My Production App",
    "vapid_public_key": "BNbx...",
    "subscriber_count": 0,
    "settings": {
      "default_icon": "https://example.com/icon.png",
      "default_url": "https://example.com"
    },
    "created_at": "2025-06-01T08:00:00Z",
    "updated_at": "2025-06-01T08:00:00Z"
  }
}

The VAPID private key is not returned by the API

The serializer (push_controller.ex:439-449) never includes vapid_private_key, fcm_credentials, or apns_credentials — both serialize_app/1 (used by list/update) and serialize_app_full/1 (used by show/create) return only the public fields shown above. Earlier docs claimed the private key was returned once at creation time; that has never been true.

The private key is generated server-side by Push.create_app/2 (lib/krafter/push.ex:37-49) and stored encrypted at rest. To use it you currently need IEx/database access; programmatic retrieval via the API is not supported. If you need to manage the keypair yourself, pass vapid_public_key and vapid_private_key in the create payload — the worker honours Map.put_new semantics (push.ex:37-49) and only generates a key when the field is absent.

---

Get App

Retrieve details of a specific app.

GET /push/apps/:app_id

Required scope: push:read

Credentials are not returned

The serializer never returns vapid_private_key, fcm_credentials, or apns_credentials — only vapid_public_key appears in the response. See the warning under Create App for how to manage credentials in practice.

Example Request

curl https://app.krafter.dev/api/v1/push/apps/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d \
  -H "Authorization: Bearer kr_live_abc123def456"

Example Response

{
  "data": {
    "id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "name": "My Production App",
    "vapid_public_key": "BNbx...",
    "subscriber_count": 12450,
    "settings": {
      "default_icon": "https://example.com/icon.png",
      "default_url": "https://example.com"
    },
    "created_at": "2025-06-01T08:00:00Z",
    "updated_at": "2025-06-10T14:30:00Z"
  }
}

---

Update App

Update an existing app. Only provided fields are changed.

PATCH /push/apps/:app_id

Required scope: push:write

Request Body

Field	Type	Required	Description
name	string	No	Display name for the app.
settings	object	No	Default notification settings.

Example Request

curl -X PATCH https://app.krafter.dev/api/v1/push/apps/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d \
  -H "Authorization: Bearer kr_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production App (Renamed)",
    "settings": {
      "default_icon": "https://example.com/new-icon.png",
      "default_url": "https://example.com"
    }
  }'

Example Response

{
  "data": {
    "id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "name": "Production App (Renamed)",
    "vapid_public_key": "BNbx...",
    "subscriber_count": 12450,
    "settings": {
      "default_icon": "https://example.com/new-icon.png",
      "default_url": "https://example.com"
    },
    "created_at": "2025-06-01T08:00:00Z",
    "updated_at": "2025-06-12T09:15:00Z"
  }
}

---

Delete App

Permanently delete an app and all its subscribers, notifications, and webhooks.

DELETE /push/apps/:app_id

Required scope: push:write

Example Request

curl -X DELETE https://app.krafter.dev/api/v1/push/apps/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d \
  -H "Authorization: Bearer kr_live_abc123def456"

Example Response

// 204 No Content