Apple Push Notification service_
Send push notifications to apps on Apple devices through Apple Push Notification service (APNs) using Appwrite Messaging.
8 min read
Apple Push Notification service (APNs) lets you send push notifications to Apple devices like macOS, iOS, tvOS, iPadOS, and watchOS devices. APNs is a best-effort service, and will attempt to deliver you messages to your device when it's online and available again. APNs will save the last message for 30 days or less and attempt delivery as soon as it's online.
One-click setup with the CLI
The Appwrite CLI sets up APNs for an iOS app in one command. Run it from your app's project folder:
appwrite init apnsThe command reads the bundle ID and team ID from your Xcode project (or app.json for Expo), and the key ID from the AuthKey_<KEYID>.p8 file name. It then:
- Creates or updates two APNs providers, production and sandbox, and enables them.
- Adds the
aps-environmententitlement and theremote-notificationbackground mode to your Xcode target. If the target has no entitlements file orInfo.plist, the CLI tells you which capability to add in Xcode instead. - Adds an Apple platform for the bundle ID to your project if it has none. Without one, Appwrite rejects your app's requests, device registration included.
- Checks with Apple that the bundle ID is registered as an App ID with Push Notifications turned on. APNs rejects pushes for any other bundle ID with
TopicDisallowed. The CLI asks before it signs in to Apple or changes anything.
In an Expo project, also set the entitlement and background mode in app.json, because expo prebuild regenerates the ios folder. The CLI prints the exact keys to add.
Provide a key
The CLI needs an APNs auth key (.p8). Use one you already have, or let the CLI create one:
- A
.p8in your project folder. Runappwrite init apns. The CLI uses the key without asking, or lets you pick one if there are several. - A
.p8stored somewhere else. Pass--key-pathwith the file's path. Add--team-idif your project doesn't set a team. - A new key from your Apple ID. Pass
--create-key. The CLI signs in with your Apple ID, password, and two-factor code, then creates the key. This option is experimental. - A new key from the Apple Developer portal. Run
appwrite init apnsand pick the portal. The CLI opens it and waits up to 15 minutes for the downloaded.p8to appear in your project folder or~/Downloads.
When the CLI finds no key and you don't pass --create-key or --key-path, it asks which way you want.
When the CLI creates a key:
- It saves the key as
AuthKey_<KEYID>.p8in your project folder. Apple lets you download a key only once, so keep the file somewhere safe and out of version control. The CLI warns you when git would commit it. - Apple allows two APNs keys per team, and one key works for every app on the team. When both are taken, the CLI lists them and stops. Pass
--key-pathwith a key you saved earlier, or revoke one you no longer use in the Apple Developer portal. - It saves your Apple sign-in, so later runs skip the password and two-factor code until Apple expires the session. The
appwriteandexposetups keep it in~/.appwrite/apns/<setup>/, readable only by you. Thefastlanesetup uses fastlane's own saved session.--resetsigns in again and creates a new key.
The CLI can sign in to Apple in three ways. Pick one with --provider or the APPWRITE_APNS_SETUP environment variable. If one stops working, switch to another.
| Setup | Built on |
|---|---|
appwrite (default) | The CLI's own Apple client |
expo | @expo/apple-utils |
fastlane | fastlane's spaceship |
--provider only picks how the CLI signs in to Apple. It doesn't change the APNs providers in your Appwrite project.
Run it again
You can run appwrite init apns as often as you like. It never creates duplicate providers. What it does with the key depends on the providers you already have:
- Both providers are set up and enabled. The CLI keeps both providers and their key. It still updates Xcode, adds the Apple platform if it's missing, and checks the App ID.
--create-keyalone changes nothing here. - You pass
--force,--key-path, or--reset. The CLI puts the new key on both providers. - One or both providers are missing or disabled. The CLI gets a key as on a first run, then creates or updates both providers with it, including one that was already working.
To create a new key for providers that already work, pass --create-key --force.
Options
| Flag | Description | When omitted |
|---|---|---|
--bundle-id <id> | iOS bundle ID. | PRODUCT_BUNDLE_IDENTIFIER of the app target, or ios.bundleIdentifier in Expo's app.json or app.config.json. If there are several apps, the CLI lets you pick one. If there are none, it asks. |
--team-id <id> | 10-character Apple Developer team ID. | The target's DEVELOPMENT_TEAM, Expo ios.appleTeamId, or the team on an existing provider. With --create-key, picked during the Apple sign-in. |
--key-path <file> | An existing APNs auth key (.p8). Replaces the key on providers that are already set up. | A valid .p8 in the project folder. If there is none, the CLI asks. |
--key-id <id> | 10-character key ID. | Read from the AuthKey_<KEYID>.p8 file name. If the name has no key ID, the CLI asks. A created key uses the ID Apple gives it. |
--create-key | Create the key by signing in with your Apple ID. When both providers are already set up and enabled, also pass --force. | Offered when no key is found. |
--provider <setup> | How the CLI signs in to Apple: appwrite, expo or fastlane. Not an Appwrite messaging provider. | APPWRITE_APNS_SETUP if set, otherwise appwrite. |
--environment <env> | production, sandbox or all. | all |
--reset | Sign in to Apple again instead of reusing the saved sign-in. Implies --create-key, so it creates a new key. | The saved sign-in is reused. |
--register-app-id | Register the App ID and turn on Push Notifications without asking. Fails if that can't be done. Experimental. | The CLI still checks the App ID on every run, and asks before it changes anything. |
--force | Replace the key on providers that are already set up. | When both providers are set up and enabled, they keep their key. Otherwise, both get the key you provide. |
--create-key and --reset can't be combined with --key-path or --key-id.
Run in CI
Without a terminal, the CLI can't ask for a two-factor code or show a picker. In CI:
- Pass an existing key with
--key-path. Creating a key always needs a two-factor code. - Pass
--bundle-idwhen your project has more than one app, and--team-idwhen it doesn't set a team. - Set
APPWRITE_APPLE_IDandAPPWRITE_APPLE_PASSWORDto answer the Apple ID and password prompts. The CLI never prints their values. - The App ID check uses a saved Apple sign-in if there is one, and otherwise reports that it skipped the check. It only fails the command when you pass
--register-app-id.
appwrite init apns --key-path ./AuthKey_Q4GAU66T2N.p8 --bundle-id com.example.app --team-id ABCDE12345What the CLI leaves to you
The CLI sets up the providers and your project, not your app's code. To receive pushes, request notification permission in the app, register the device token as a push target, and send a test message, as described in Send push notifications.
To set up APNs from the Console instead, follow the steps below.
1. Add provider
To add APNs as a provider, navigate to Messaging > Providers > Create provider > Push notification.

Give your provider a name > choose APNS > click Save and continue. The provider will be saved to your project, but not enabled until you complete its configuration.
2. Configure provider
In the Configure step, you will need to provide details from your Apple developer account to connect your Appwrite project with your Apple developer account.
You will need to provide the following information from the Apple Developer Member Center.
Head to Apple Developer Member Center > Membership details > Team ID

Head to Apple Developer Member Center > Program resources > Certificates, Identifiers & Profiles > Identifiers

Head to Apple Developer Member Center > Program resources > Certificates, Identifiers & Profiles > Keys. Click on your key to view details. The key needs Apple Push Notification Service enabled.

Head to Apple Developer Member Center > Program resources > Certificates, Identifiers & Profiles > Keys. Create a key and give it a name. Enable the Apple Push Notifications service (APNS), and register your key. The key needs Apple Push Notification Service enabled.

Enable sandbox mode for testing on apps signed with development provisioning profiles. APNs offers two environments, Development (sandbox) and Production. Development builds on XCode signed with a development provisioning profile will use the development environment. Production builds signed with a production provisioning profile will use the production environment.
After adding the following details, click Save and continue to enable the provider.
3. Configure app
Some additional configuration is required to enable push notifications in your iOS app. Add push notification capability to your app by clicking your root-level app in XCode > Signing & Capabilities > Capabilities > Search for Push Notifications.

4. Test provider
Push notification requires special handling on the client side. Follow the Send push notification flow to test your provider.
5. Manage provider
You can update or delete a provider in the Appwrite Console.
Navigate to Messaging > Providers > click your provider. In the settings, you can update a provider's configuration or delete the provider.
To update or delete providers programmatically, use an Appwrite Server SDK.
const sdk = require('node-appwrite');
// Init SDKconst client = new sdk.Client();
const messaging = new sdk.Messaging(client);
client .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') // Your API Endpoint .setProject('<PROJECT_ID>') // Your project ID .setKey('919c2d18fb5d4...a2ae413da83346ad2') // Your secret API key;
const provider = await messaging.updateApnsProvider({ providerId: '<PROVIDER_ID>', name: '<NAME>', enabled: false, authKey: '<AUTH_KEY>', authKeyId: '<AUTH_KEY_ID>', teamId: '<TEAM_ID>', bundleId: '<BUNDLE_ID>'});Was this page helpful?
Share what worked or what we should fix. Once approved, our agents automatically apply suggested updates to the docs.