Skip to main content
Sending push notifications to iOS or macOS apps requires an authenticated connection to Apple Push Notification service (APNs). You can authenticate using a token-based (.p8 key) or a certificate-based (.p12 file) method. Only one is necessary. This guide covers the token-based .p8 key, the recommended approach.

​
Requirements

Make sure you have the following before starting:

​
Set up APNs authentication

​
Generate your .p8 key in Apple Developer Account

For Apple’s full instructions, see Create a private key to access a service.
  1. Log into your Apple Developer Account.
  2. Go to Certificates, Identifiers & Profiles > Keys.
  3. Click the blue plus (+) icon. If you don’t see it, contact your Admin for access.
Apple Developer Keys page showing the blue plus icon to create a new key
  1. Select Apple Push Notifications service (APNs).
  2. When configuring the key, ensure that Sandbox & Production is selected:
Apple Developer key configuration with Sandbox and Production selected
Apple’s docs lean toward creating separate keys for Sandbox and Production, but OneSignal requires a single team-scoped key valid in both environments.If you need 2 separate environments, you can create separate OneSignal apps for each environment.
  1. Enter a name for the key and click Continue, then Register.
Apple Developer key registration page with Continue and Register buttons
  1. Download your .p8 key and store it securely. You won’t be able to download it again.

​
Upload the .p8 key to OneSignal

  1. Navigate to Settings > Push & In-App > Apple iOS (APNs) Settings in your OneSignal dashboard.
OneSignal Settings page showing Push and In-App section with Apple iOS APNs settings
  1. Choose .p8 Auth Key (Recommended) as the authentication method.
OneSignal APNs authentication method selection showing p8 Auth Key recommended option
Provide the following:
  • .p8 File – The private key file you downloaded from your Apple Developer account.
  • Key ID – A 10-character alphanumeric string (e.g., ABC123DEFG) found next to your key name in the Keys section of your Apple Developer account. Make sure it matches the downloaded .p8 file.
  • Team ID – A 10-character alphanumeric string (e.g., 9A1B2C3D4E) shown next to your team name in the top-right corner of your Apple Developer account. This is not the same as the Key ID.
  • App Bundle ID – A reverse-domain string (e.g., com.example.app) found in:
    • The Identifiers section of your Apple Developer account, or
    • Xcode > Main App Target > Signing & Capabilities
Apple Developer account showing Key ID and Team ID locations
Xcode Signing and Capabilities tab showing the Bundle Identifier field
Click Save & Continue when done.
You’ve successfully set up APNs authentication using a .p8 key in OneSignal.Your iOS app is now ready to send and receive push notifications! 🎉

​
Troubleshoot APNs errors

OneSignal authenticates your .p8 key against Apple Push Notification service when you save it, and APNs continues to return response codes for individual notifications at send time. If Apple rejects your credentials at save or reports a delivery failure, find the fix below.
For the complete list of APNs response codes, see Apple’s Handling notification responses from APNs.

​
InvalidProviderToken (403)

Apple couldn’t authenticate this key. The .p8 file, Key ID, or Team ID doesn’t match, or the key was revoked in Apple Developer. Apple returns this same response for all four causes. To fix:
  1. In your Apple Developer account, open the key and confirm it is Active with Apple Push Notifications service enabled.
  2. Copy the Key ID shown on that page into the Key ID field, exactly.
  3. Copy your Team ID from your Apple Developer Membership details into the Team ID field.
  4. If everything above matches, the key may have been revoked. Create a new .p8 key, download it, and upload it here with its Key ID.
Key ID and Team ID are both 10-character strings and easy to swap by accident. This is the most common cause of InvalidProviderToken.

​
TopicDisallowed or MissingTopic

Your key is valid, but the App Bundle ID doesn’t match an app registered under this Apple team. To fix:
  1. In Xcode, open your app and copy the Bundle Identifier from your target’s Signing & Capabilities tab. Do not use the OneSignalNotificationServiceExtension Bundle ID with .OneSignalNotificationServiceExtension.
  2. Paste it into the App Bundle ID field, exactly. Bundle IDs are case-sensitive.
  3. Confirm the same Bundle ID appears under Identifiers in the Apple Developer account where your key was created.

​
BadEnvironmentKeyInToken (403)

Your key is restricted to a single environment (Sandbox-only or Production-only), but OneSignal requires a key valid in both environments. To fix:
  1. In your Apple Developer account, create a new key with Apple Push Notifications service enabled.
  2. Under Environment, select Sandbox & Production.
  3. Under Key Restriction, select Team Scoped (All Topics).
  4. Download the new .p8 and upload it here with its Key ID.
Send-time errors are returned when a notification is rejected on its way to a device. Find these in your delivery statistics.

​
InvalidProviderToken (after previously working)

If notifications suddenly start failing with InvalidProviderToken and you haven’t changed your credentials, the .p8 key was most likely revoked in Apple Developer. Apple doesn’t return a dedicated “revoked” code. To fix: Create a new .p8 key, download it, and upload it here with its Key ID and your Team ID. For the full list of delivery response codes, see Push notification message reports.

​
Other checks

If you’re not seeing one of the response codes above, work through these general checks.
1

Check the .p8 file format

Open the .p8 file in a text editor. It should look like this:
2

Confirm you didn't upload a .p12 by mistake

  • .p8 keys come from the Keys section of your Apple Developer account.
  • .p12 certificates come from the Certificates section and are not compatible with .p8 authentication. Use the .p12 setup guide if that’s the flow you want.
3

Confirm the key has APNs capability

When viewing the key in Apple Developer, Apple Push Notifications service (APNs) should be listed as an enabled service. If not, revoke the key and create a new one.
4

Wait a few minutes after creating a new key

Newly created keys may take 10–15 minutes to propagate before Apple allows external authentication. If you get errors immediately after creating a key, wait and try again.

​
Need help?

  • Revoke the current .p8 key and create a new one from scratch.
  • Double-check you’re using a valid Bundle ID from the same Apple Developer account the key was created under.
  • Reach out to support@onesignal.com with a screenshot of your Apple Developer key configuration and the Key ID, Team ID, and Bundle ID you entered in OneSignal.

​
Next steps

iOS SDK setup

Install the OneSignal SDK, initialize it in your app, and send a test notification.

Mobile SDK setup

Choose your platform and follow the full SDK integration guide for Android, iOS, or cross-platform frameworks.

​
FAQ

​
What’s the difference between .p8 and .p12?

A .p8 key is a token-based authentication key that does not expire and works across all apps under your Apple Developer account. A .p12 certificate is app-specific and expires after one year, requiring annual renewal. OneSignal recommends .p8 for its simplicity and lower maintenance. See the .p12 certificate guide for the alternative method.

​
Does my .p8 key expire?

No. Unlike .p12 certificates, .p8 keys do not expire. Once created, a .p8 key remains valid until you revoke it in your Apple Developer account.

​
Can I use one .p8 key for multiple apps?

Yes. A single .p8 key works for all apps under the same Apple Developer account. You can upload the same .p8 file to multiple OneSignal apps. Each app only needs its own unique Bundle ID.

​
Do I need a provisioning profile, and how do I create one?

Yes, Apple requires different types of profiles for development, testing (Ad Hoc), and distribution to the App Store. In Xcode, select Automatically manage signing to create one automatically.
Xcode Signing and Capabilities tab with Automatically manage signing enabled
Otherwise, see Apple’s docs on provisioning profiles for details.