---
title: Apple APNs
description: Configure Apple Push Notification service in Notiflows
---

Apple Push Notification service (APNs) delivers push notifications to iOS, iPadOS, macOS, watchOS, and tvOS devices.

## Prerequisites

Before configuring APNs in Notiflows, you need:

1. An [Apple Developer](https://developer.apple.com) account
2. An App ID with Push Notifications capability enabled
3. Either an APNs authentication key (`.p8` file) or a push certificate — see [Authentication methods](#authentication-methods) below

## Configuration

| Field | Required | Description |
|-------|----------|-------------|
| Bundle ID | Yes | Your app's bundle identifier (e.g., `com.example.myapp`) |
| Environment | Yes | **Production** for App Store builds, **Sandbox** for development |
| Auth Type | Yes | **Key** (recommended) or **Certificate** |

## Authentication methods

APNs supports two authentication methods. You only need one.

### Token-based authentication (recommended)

Token-based authentication uses a signing key that Apple issues once per account. A single key works across all your apps and doesn't expire, making it the simpler option for most teams.

| Field | Required | Description |
|-------|----------|-------------|
| Key ID | Yes | 10-character identifier shown when you download the key |
| Team ID | Yes | 10-character identifier found in your Apple Developer account membership |
| Key | Yes | Contents of your `.p8` key file |

**How to get your signing key:**

1. Go to [Certificates, Identifiers & Profiles](https://developer.apple.com/account/resources) in your Apple Developer account
2. Navigate to **Keys** and click the **+** button
3. Name the key, check **Apple Push Notifications service (APNs)**, and click **Continue**
4. Click **Register**, then **Download** the `.p8` file
5. Note the **Key ID** displayed on the confirmation page

<Callout>
Apple only lets you download the `.p8` file once. Store it securely. If you lose it, you'll need to revoke the key and create a new one.
</Callout>

Open the `.p8` file in a text editor and paste the full contents (including the `-----BEGIN PRIVATE KEY-----` and `-----END PRIVATE KEY-----` lines) into the **Key** field in Notiflows.

For more details, see Apple's guide on [establishing a token-based connection to APNs](https://developer.apple.com/documentation/usernotifications/establishing-a-token-based-connection-to-apns).

### Certificate-based authentication

Certificate-based authentication uses a TLS client certificate specific to a single app. Certificates expire after one year and must be renewed.

| Field | Required | Description |
|-------|----------|-------------|
| Certificate | Yes | X.509 certificate in PEM format |
| Private Key | Yes | Unencrypted private key in PEM format |

**How to get your push certificate:**

1. Go to [Certificates, Identifiers & Profiles](https://developer.apple.com/account/resources) in your Apple Developer account
2. Navigate to **Identifiers**, select your App ID, and enable **Push Notifications**
3. Click **Configure** and create a certificate for your environment (Development or Production)
4. Follow the prompts to upload a Certificate Signing Request (CSR) and download the `.cer` file
5. Open the `.cer` file in Keychain Access, then export it as a `.p12` file

For more details, see Apple's guide on [establishing a certificate-based connection to APNs](https://developer.apple.com/documentation/usernotifications/establishing-a-certificate-based-connection-to-apns).

**Converting your `.p12` to PEM format:**

Notiflows expects PEM-formatted strings. Use the following commands to convert your `.p12` file:

Extract the certificate:

```bash
openssl pkcs12 -clcerts -nokeys -out cert.pem -in cert.p12
```

Extract the private key (you'll be prompted to set a passphrase):

```bash
openssl pkcs12 -nocerts -out key.pem -in cert.p12
```

Remove the passphrase from the private key:

```bash
openssl rsa -in key.pem -out key_unencrypted.pem
```

Paste the contents of `cert.pem` into the **Certificate** field and `key_unencrypted.pem` into the **Private Key** field in Notiflows.

<Callout>
Push certificates are tied to a specific app and environment. You'll need separate certificates for development and production. Token-based authentication avoids this limitation — one key covers all apps and both environments.
</Callout>

## Setup in Notiflows

1. Navigate to **Channels** in your project
2. Click **Create Channel**
3. Select **Mobile Push** as the channel type
4. Select **Apple APNs** as the provider
5. Enter your **Bundle ID**
6. Select the **Environment** (Production or Sandbox)
7. Choose your **Auth Type** and enter the corresponding credentials
8. Save the channel

## Syncing device tokens

To deliver push notifications, Notiflows needs the APNs device token for each user. Your app receives this token from Apple at runtime and must sync it to Notiflows via the User API.

Set the device token as a channel setting on the user:

```bash
curl -X PUT https://api.notiflows.com/user/v1/channel-settings \
  -H "Authorization: Bearer USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "YOUR_APNS_CHANNEL_ID",
    "settings": {
      "device_tokens": ["DEVICE_TOKEN_FROM_APPLE"]
    }
  }'
```

A user can have multiple device tokens (one per device). Notiflows sends the notification to the first token in the list.

## Payload

When Notiflows delivers a push notification via APNs, the payload includes all configured fields. Only non-empty template fields are included.

```json
{
  "aps": {
    "alert": {
      "title": "Rendered title",
      "body": "Rendered body",
      "subtitle": "Rendered subtitle"
    },
    "sound": "default",
    "badge": 3,
    "category": "MESSAGE_REPLY",
    "thread-id": "conv_456",
    "mutable-content": 1,
    "interruption-level": "time-sensitive",
    "relevance-score": 0.8
  },
  "notiflows_notification_id": "notif_abc123",
  "notiflows_delivery_id": "del_xyz789",
  "notiflows_image_url": "https://cdn.example.com/image.png",
  "notiflows_action_url": "https://app.com/orders/123",
  "notiflows_data": {}
}
```

The `mutable-content` flag is set automatically when an image URL is configured, enabling your [Notification Service Extension](https://developer.apple.com/documentation/usernotifications/unnotificationserviceextension) to download and attach the image.

APNs headers are also set when applicable:

| Header | When set |
|--------|----------|
| `apns-collapse-id` | When Collapse ID is configured |
| `apns-priority` | `5` when Priority is set to normal |
| `apns-expiration` | Computed from TTL (current time + TTL seconds) |

## APNs-specific template fields

These fields are only shown when the channel provider is APNs:

| Field | Description |
|-------|-------------|
| **Subtitle** | Secondary text between title and body |
| **Interruption Level** | Controls [Focus mode](https://developer.apple.com/documentation/usernotifications/unnotificationinterruptionlevel) behavior |
| **Relevance Score** | Ranking in [Notification Summary](https://developer.apple.com/documentation/usernotifications/unnotificationcontent/relevancescore) (0.0–1.0) |

See the [Mobile Push overview](/docs/channels-providers/mobile-push) for all shared template fields.