Migrate to .p8 Key Based Authentication for Apple Push Notification Service (APNs)

If you have previously integrated Teak on iOS, you most likely use Apple APNs Certificate Based (.p12) Authentication which must be renewed annually. This guide will walk you through switching to Apple APNs Key Based (.p8) Authentication which does not need to be renewed.

The required steps can be done in the Teak and Apple Developer dashboards. No client update is required.

You will need the following to complete this step:

  • A game with APNs Certificates (.p12 Files) setup in Teak

  • An account on the Apple Developer Site with Administrator permissions

  • An account on Teak with access to your game

  • An iOS test device that can receive push notifications for your game

Two Key Limit

Each Apple Developer Team may only have two Keys with Apple Push Notification service (APNs) enabled. You may use the same Key for multiple games and push notification providers.

Do not revoke existing keys in your account unless you can confirm that they are not in active use.

Create the Key

  1. Navigate to the Keys list on your Apple Developer account.

  2. Click the plus sign next to "Keys" to bring up new key registration.

  3. Give your new Key a name to indicate how it is being used, for example TeakPushKey

  4. Check the box to enable Apple Push Notifications service (APNs)

    new key
    If the Apple Developer Team already has two Keys with Apple Push Notification service (APNs) enabled, you will be unable to create a new key. You must consult with your team and existing uses of Apple Developer Team keys to either use an existing Key with Teak or to identify a Key that may be revoked so that you can create a new Key.

  5. Click on Continue to verify key settings.

  6. On the confirmation page confirm that the Key Name is correct and that Apple Push Notification service (APNs) is enabled.

  7. Click on Register to create the key.

    confirm key

  8. Click on Download to download the key.

    Your Team may only download the key once.

    If you are not prepared to save the key in a safe location or upload it to Teak, stop here. Coordinate with your team to store the key for future use.

    If you have multiple games in a single Apple Developer Team, each game will need a copy of the key you just created.

  9. Save the key to a location where other members of your or company team may access it.

    This key can be used for other games, so ensure that the key is saved to a location where developers on other games may access it.

Uploading to Teak

Now that the Apple Developer Team key is saved, we just have to add it to Teak!

  1. In the Teak Dashboard, navigate to Settings  iOS for your game, and click Setup .p8 Key Authentication.

    new teak settings

  2. In the modal that appears, click Select .p8 Key File and select the .p8 file you just downloaded.

  3. Enter the Key ID for the key and Team ID for your Apple Developer Team.

  4. Enter the Bundle ID for your game. This should match the Bundle ID for an existing APNs Certificates (.p12 Files) configured for your game in Teak.

  5. Click Save to upload your Apple Developer Team Key to Teak.

If this is not a Production environment on Teak, you are done. Proceed to your normal testing to make sure everything is working. If this is a Production build, then there’s a few more steps to take to make sure we don’t break anything.

Extra Steps for Production builds

For Production environments, we want to make sure the new credentials are working before we rollover to the new credentials.

Preview a test notification

  1. In a new tab, send yourself a Preview Notification to your iOS device.

    See Sending Your First Notification for directions on setting up and sending previews notifications.

  2. When the Teak detects that there were no errors with your preview send, you will see Preview Successful! in the setup modal.

    This will work without an app update. The credentials are used in the backend, so no client update is required.
    Troubleshooting

    If things are not sending properly, the most likely cause downloading a key from the wrong Apple Developer Team. Double check that your game’s Bundle ID appears in the Identifer column in the Certificates, Identifiers & Profiles list on your Apple Developer account.

Begin Rollout

  1. With the Preview send confirmed, it’s time to click Begin Rollout.

    The modal outlines the process:

    • Teak will start sending 1% of sends using Key Based (.p8) authentication.

    • If sends continue to work properly, Teak will direct an additional 1% of sends each hour until the game has fully rolled over to Key Based (.p8) authentication.

    • It should take approximately 4 days for the full rollout to complete.

  2. If your game has notification sends going out, you will see the "successful sends" number increasing every minute.

    Teak will monitor the error rate. If it appears abnormal, the rollout will be canceled.

Wait 4 days…​

…​ FOUR DAYS LATER…​

  1. In the Teak Dashboard again, navigate to Settings  iOS. The progress bar will be gone when it’s all done.

  2. Congratulations, you have switched to Key Based (.p8) Authentication and no longer need to renew .p12 certificates!