Skip to main content

Getting your APNs credentials (iOS)

Joryio sends push notifications to iOS devices through the Apple Push Notification service (APNs). To do that it needs credentials from your Apple Developer account. This page walks through creating them in Apple's portal and entering them in Joryio.

Each Joryio app holds its own push credentials, so you do this once per iOS app. A React Native or Unity project has a separate iOS app in Joryio - its APNs credentials go there. See Multi-Platform Tracking.

What Joryio asks for​

Joryio uses token-based authentication with an APNs auth key (a .p8 file). You need four things:

Field in JoryioWhat it isWhere it comes from
EnvironmentDevelopment (Sandbox) or Production - which APNs environment your app's builds register withYour build type - see Choose the environment
Key ID10-character identifier of the auth keyApple Developer account, Keys
Team ID10-character identifier of your Apple developer teamApple Developer account, Membership details
Auth Key (.p8 Content)The full text of the .p8 fileThe file you download once when you create the key

The push settings also offer a Certificate-Based (.p12) authentication method. This guide covers the token-based .p8 key only, which is the recommended method: an auth key does not expire, and one key can send for every app in your Apple developer team.

Before you start​

  • An Apple Developer Program membership. APNs keys are created in a paid developer account.
  • The Account Holder or Admin role in that developer team. Apple only lets these roles create keys. If you have another role, ask your Account Holder or an Admin to create the key and send you the Key ID, the Team ID, and the .p8 file through a secure channel.
  • Push Notifications enabled for your app. In Xcode, add the Push Notifications capability to your app target, and make sure push notifications are enabled for the App ID (the bundle ID) in your developer account. The key must belong to the same developer team as the app.
  • An iOS app in Joryio with the iOS SDK integrated. To create one, see Creating Apps.

Step 1: Create the APNs auth key​

  1. Sign in to your Apple Developer account and open Certificates, Identifiers & Profiles.
  2. Click Keys in the sidebar, then click the add button (+).
  3. Under Key Name, enter a name you will recognize later, for example "Joryio push".
  4. Select the checkbox next to Apple Push Notification service (APNs), then click Configure next to it.
  5. Choose the environment for the key and the key type:
    • Environment - pick the environment that matches the one you will select in Joryio (see Choose the environment). A key restricted to Sandbox does not work for production sends, and the reverse.
    • Key type - Team Scoped works for every app (bundle ID) in your team. Topic Specific is limited to the bundle IDs you select - if you choose it, include your app's bundle ID.
  6. Click Continue, review the key configuration, then click Confirm.
  7. Click Download. The key is saved as a text file with a .p8 extension.
  8. Click Done.
You can download the key only once

Apple does not keep a copy of the private key. Store the .p8 file somewhere safe, such as your team's password manager. If the Download button is disabled later, the key was already downloaded. If the file is lost, create a new key and revoke the old one.

Step 2: Note the Key ID and the Team ID​

  • Key ID - In Certificates, Identifiers & Profiles → Keys, click the key you created. The Key ID is shown in the key details, below the key name.
  • Team ID - In your Apple Developer account, open Membership details. The Team ID is a 10-character string.

Step 3: Choose the environment​

APNs has two environments, and a device token only works in the environment it was issued for:

  • Development (Sandbox) - for builds signed with a development provisioning profile, for example when you run the app from Xcode on your own device.
  • Production - for builds signed with a distribution provisioning profile: the App Store and TestFlight.

Xcode sets the app's push environment from the provisioning profile, so the build decides which environment its devices register with. Each Joryio app has one environment setting. If you test with development builds and also ship to the App Store, create a separate Joryio iOS app for the development builds (with its own SDK key), rather than switching the setting back and forth.

Step 4: Enter the credentials in Joryio​

  1. In the Joryio dashboard, go to Settings → Apps.
  2. Find your iOS app in the list and click the Push Notifications (bell) icon on its row. The Push notifications - [app name] page opens.
  3. In the APNS credentials card:
    • Environment - choose Development (Sandbox) or Production.
    • Authentication Method - choose Token-Based (.p8 Key).
    • Key ID - paste the Key ID from step 2.
    • Team ID - paste the Team ID from step 2.
    • Auth Key (.p8 Content) - open the .p8 file in a text editor and paste its entire content, including the -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY----- lines.
  4. Click Save configuration.

The apps list now shows APNS configured under the app's name. The auth key is encrypted at rest and is never shown again: when you reopen the page, the field is empty with the note "Configured - leave blank to keep the current value, or enter a new one to replace it." Leave it blank to keep the saved key.

Step 5: Send a test push​

  1. Install a build of your app whose environment matches the one you chose, open it, and allow notifications. The SDK registers the device's token with Joryio.
  2. Create a push campaign (or open a draft) that sends from this app.
  3. Click Send test push on the variant, choose the user who is signed in on your device, and send.

If the test fails, the error message includes the reason APNs returned - look it up in the table below. See Push Notifications for the full campaign flow.

Common errors and fixes​

What you seeLikely causeFix
BadDeviceTokenThe device token was issued for the other environment - for example a TestFlight build while Joryio is set to Development (Sandbox).Set Environment to match the build (see step 3), then open the app on the device again so it registers its token again.
DeviceTokenNotForTopicThe token belongs to a different app (bundle ID) than the one the credentials send for.Check that the device runs the app connected to this Joryio app's SDK key, and that the key belongs to the developer team that owns the app.
InvalidProviderTokenThe Key ID, the Team ID, or the .p8 content does not match - for example a Key ID from one key with the content of another, or a key from a different team.Re-enter all three values from the same key and team. Paste the whole .p8 file, including the BEGIN and END lines.
TopicDisallowedThe key is not allowed to send to this app - for example a Topic Specific key that does not include your bundle ID, or a key restricted to the other environment.Create a key that covers your bundle ID and environment, or use a Team Scoped key.
UnregisteredThe app was uninstalled or the token is no longer active.Nothing to fix in the credentials. Joryio stops sending to that token.
"no device accepted the notification"The user has no registered iOS device for this app.Open the app on the device with the SDK integrated, allow notifications, and make sure you test with the same user.
The key file is lostApple only allows one download.Create a new key (step 1), enter it in Joryio, then revoke the old key.
A key was revokedEvery send with that key fails.Create a new key and enter it in Joryio.

Security and rotation​

  • Treat the .p8 file as a secret: anyone who has it, with your Key ID and Team ID, can send notifications to your users. Do not commit it to source control or send it by email or chat.
  • If you think the key has leaked, create a new key, enter it in Joryio, then revoke the old one: in Certificates, Identifiers & Profiles → Keys, click the key, click Revoke, and confirm. Revoking takes effect right away for every service that uses the key.
  • To rotate the key without downtime, do it in the same order: new key in Joryio first, revoke the old one second. Apple limits how many keys a team can have per environment, so you may need to revoke an unused key before creating a new one.