Configuring APNs Credentials

Futurae Command & Control (C&C) — JWT Token-Based Setup Guide

Overview

This guide walks you through configuring Apple Push Notification service (APNs) credentials for your Futurae-powered mobile application using JWT token-based authentication.

Token-based authentication uses a .p8 key file and is recommended by Apple over the older certificate-based approach (.p12) for the following reasons:

• No expiry: The key does not expire, unlike certificates which require annual renewal.
• No outage risk: Expired certificates silently stop push delivery. Token-based auth eliminates this risk.
• One key, two environments: A single .p8 key can authenticate against both the Sandbox and Production APNs endpoints.

Prerequisites

Before you begin, confirm you have the following:

• Apple Developer Program membership with access to Certificates, Identifiers & Profiles.
• Your app's Bundle Identifier (e.g., com.companyname.appname). Find this in Xcode under your target's General tab.
• Admin or Owner role in the Futurae Command & Control Dashboard.
• A secure location to store the .p8 key file  Apple only allows you to download it once.

1. Understanding Sandbox vs. Production Environments

Apple operates two separate APNs environments: Sandbox (for development) and Production. Each Futurae Service can only connect to one APNs environment at a time.

To support both your development and release pipelines without credential switching, create two separate Services in your Futurae C&C Dashboard:

⚠️  Environment mismatch causes silent delivery failure. If a device is registered on the APNs Production environment and a notification is sent via the Sandbox endpoint (or vice versa), the push will fail silently, the user will not receive the notification and no visible error will be shown in your app. Always ensure your Futurae service, APNs endpoint, and the build type of the enrolled device all match.

ℹ️  Make sure any firewalls or outbound network rules in your environment allow HTTPS traffic on port 443 to both api.push.apple.com and api.sandbox.push.apple.com.

2. Create an APNs Key in Apple Developer

This key (.p8 file) is what Futurae uses to authenticate with Apple's APNs servers on your behalf.

1. Log into your Apple Developer Account 
2. Navigate to Certificates, Identifiers & Profiles > Keys.
3. Click the + (plus) button to create a new key.
4. Enter a recognizable Key Name (e.g., CompanyName APNs Auth Key). 
5. Check the Apple Push Notifications service (APNs) checkbox.
6. Click Configure to set the environment and scope:
   • Environment: Choose Sandbox & Production (this ensures the single key can be used for both your separate testing and production Futurae services).
   • Key Restriction: Choose Team Scoped (All Topics) unless your organization requires specific restrictions.

⚠️ Important: The environment and restriction settings cannot be changed after the key is created. Double-check your selections before proceeding.

7. Click Save, review the summary, click Continue, and then Register.
8. Download the .p8 key file. 

 ⚠️ Important: Apple allows you to download this file exactly once. If you lose it, you must revoke the key and create a new one. This will interrupt push notifications until the new key is configured in Futurae. Store the file in a secure password manager or secrets vault immediately.

9. On the key detail page, copy and save both of the following values, you will need them in the next section:

• Key ID: the 10-character alphanumeric identifier shown under the key name.
• Team ID: your Apple Team ID, visible in the top-right corner of the developer portal, or under Membership in account settings.

3. Configure the Credentials in Futurae C&C Platform

If you have Admin or Owner access to the Futurae Command & Control Dashboard, repeat this process for both your Development service (Service A) and your Production service (Service B), using the appropriate Production toggle setting each time:

1. Log in to the Futurae Command & Control Dashboard.
2. Navigate to Service > Settings > Mobile SDK.
3. Click Edit APNS Credentials.
4. Select the JWT Token option and fill in the following details:
   • Authentication Key: Open your downloaded .p8 file in a text editor and paste the entire text content here, including the -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY----- lines.
   • Key ID: The 10-character alphanumeric ID copied from the Apple Developer Portal in Section 2, Step 9.
   • Team ID: Your Apple Team ID from Section 2, Step 9.
   • Topic (Bundle ID): Your app's Bundle Identifier (e.g., com.companyname.appname). Must match exactly what is registered in Apple Developer.

⚠️  Review your credentials carefully before submitting. After you click Submit, the Authentication Key and the other entered values (Key ID, Team ID, and Bundle ID) will no longer be displayed in the Futurae C&C Dashboard. Ensure all values are correct before proceeding.

5. Set the Production toggle appropriately:
   • Disabled for your Sandbox/Testing service.
   • Enabled for your Live/Production service.
6. Click Submit to save.

ℹ️  After clicking Submit, the change takes effect immediately. No app restart or user re-enrollment is required.

4. Verify the Setup

After saving credentials for both services, confirm that push notifications are being delivered correctly.

Test a notification

• Trigger a push notification from your backend to a device enrolled in the relevant service.
• Confirm the notification appears on the device.

Troubleshoot common issues

If notifications are not arriving, check the following before contacting support:

• Wrong Bundle ID: The Topic field must match the app's Bundle Identifier exactly, including case. A mismatch causes Apple to silently reject the notification.
• Environment mismatch: Development builds must use Service A (toggle Disabled). Production/TestFlight builds must use Service B (toggle Enabled). See the warning in Section 1.
• Incomplete key contents: Ensure you pasted the full .p8 file contents, including the -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY----- header and footer lines.
• Key ID / Team ID mix-up: Both are 10-character strings. Key ID is found on the Keys page; Team ID is found under Membership.
• Credentials need to be re-entered: The Futurae C&C Dashboard does not display saved APNs credentials. If you need to verify or update your configuration — for example after revoking and replacing a key — you will need to re-enter all four values.

If you have checked the above and notifications still fail, contact Futurae Support at support@futurae.com and include your Service ID, Futurae User ID and the approximate timestamp of your test. Futurae can check APNs response logs to identify the rejection reason from Apple.