An authenticated connection to Apple Push Notification Services (APNs) is required to send push notifications to all iOS mobile apps. You only need to use one authentication method, either token-based (.p8) or certificate-based (.p12). This guide will cover how to set up the token-based .p8 authentication key.

Requirements

• iOS mobile app
• Paid Apple Developer Account with Admin Role
• OneSignal Account
• Mac computer with Xcode 12+
• Xcode project with Push Notification capability added. Otherwise, your project may not be shown in the Apple Developer Center

1. Generate a p8 key

Log in to your Paid Apple Developer Account and navigate to Certificates, Identifiers & Profiles > Keys and select the Blue + button. Contact your developer account Admin if this does not appear.

Select Apple Push Notifications service (APNs), and enter a name for the key.

Select Continue and on the next page, select Register.

Download your new .p8 key and save it in a secure place. You can only download it once, so don't lose it. Then, click Done and you will have a new key.

🚧

Previous Token Revocation

You can have up to two .p8 keys in your Apple account. If you need to generate a third key, you will need to revoke one of your existing keys and it can no longer be used.

Note: .p8 keys are in the “keys” section of the Apple developer account and the .p12 certificates are under “certificates”. In your Apple account, you can only have two .p8 keys, but you can have both active .p12s and .p8s.

2. Upload Your Push Key to OneSignal

In the OneSignal dashboard, navigate to Settings > Platforms > Apple iOS (APNs) Settings.

Add or update authentication, selecting the .p8 Auth Key (Recommended) for APNs Authentication Type.

Key (.p8 file)

This is the file you downloaded in Step 1 within your Apple developer account.

Key ID & Team ID

The Key ID is the unique identifier for the p8 authentication key. You can find your Key ID in the keys section of your Apple developer account . Make sure to use the key for the same p8 key you downloaded in Step 1.

The Team ID is generated by Apple for your developer account; this can be found in the top right of your Apple developer account.

App Bundle ID

The Bundle ID identifies your app in the Apple ecosystem. You can find your Bundle ID in the Identifiers section of your Apple developer account or within Xcode > Main App Target > Signing & Capabilities.

Click Save & Continue.

👍

Done!

You should be finished generating your iOS Authentication Key and uploading it to OneSignal. You can now proceed with setting up the iOS platform.

Provisioning Profiles

Skip this step if you have selected "Automatically manage signing" in Xcode.

If you did not select "Automatically manage signing", then follow these steps.

Create Your Profile

Go to your Apple Developer Account > Certificates, Identifiers & Profiles > Profiles.

Next, find any existing profiles for your app and remove them if they do not have App Groups and Push Notifications in Enabled Capabilities:

Create a new Profile by pressing the "+" button.

Select the type of profile you need to create and press Continue.

Search for your App ID. If you do not see your App ID, check the Create Your Identifier step above.

Then press Continue.

Select the Development or Distribution Certificate to associate with the Profile. Then click Continue.

Name your Provisioning Profile.

🚧

Best Practices

When creating a new profile, make sure to enter a unique name in the "Provisioning Profile Name:" field.

For example, if you are creating an Ad-Hoc Provisioning Profile to test push notifications with a Production Push Token .p8 file. Use the format AppName_AdHoc so you know the app and type of profile that it is.

Select Generate.

On the last page Download your profile.

Re-sync your Developer Account in Xcode by going to Xcode > Preferences... then click on the "View Details..." button. Then click the refresh button on the bottom left of the popup. See Apple's documentation for more detailed instructions.

Make sure you pick your new provisioning profile from Build Settings > Code Signing > Provisioning Profile in Xcode.

Troubleshooting

"We were unable to validate the key with the information provided"

Please try opening the file with the .p8 extension that you've downloaded from your Apple developer portal. The key will have 3 rows with 64 characters and one row with 8 characters between the "BEGIN" and "END" lines.

-----BEGIN PRIVATE KEY-----
64 character line
64 character line
64 character line
8 character line
-----END PRIVATE KEY-----

After confirming this key is formatted correctly, open the p8 key from your Apple developer portal and ensure that the Key and Team ID's match what is shown in the image below. The APNs push service must also be shown here in order for this to be uploaded.

If everything matches and you're still unable to configure your Apple settings, it might mean that our request to Apple is being returned with an InvalidProviderToken which is a 403 Forbidden error that Apple returns in cases where the file is unable to be validated. In this case, you should Revoke the key and create a new one.

The key might not be immediately available after newly creating it. You should wait 10-15 minutes and then try to upload the key again.

If you have any concerns about switching from a .p12 certificate to a .p8 key with OneSignal, or if you have any issues uploading your files, please contact our Support Team.