Credentials

APNs auth key (iOS)

In your Apple Developer account, create a key with the Apple Push Notifications service enabled and download the .p8 file, which Apple lets you download once. Note its key ID, your team ID and your app's bundle ID.

Step by step, with the Xcode and Firebase settings: Set up your app.

Send them to POST /v1/push/apps as apns.key_p8 (the key text), key_id, team_id and bundle_id. The key must be the EC P-256 key Apple issues; any other kind is refused with 422 PUSH_CREDENTIAL_INVALID before Apple is asked. honkio encrypts the key at rest and no endpoint returns it.

Apple lets a key be limited to the sandbox, to production, or to both, and older keys work for both. honkio checks the key against each environment when you upload it and accepts it if it works on at least one. The response shows sandbox_status and production_status separately, so you can see which environment a restricted key covers.

A device registered for an environment the key does not cover is still sent to. Apple rejects it as a credential error, so the delivery fails, that environment is marked invalid and push_app.credentials_invalid fires. A failure in one environment never marks the other one invalid. NO_CREDENTIAL is only for an app with no credential for the device's platform.

const { data: pushApp, error } = await honkio.push.apps.create({
  name: 'Acme mobile',
  apns: {
    keyP8: process.env.APNS_KEY_P8 ?? '',
    keyId: 'ABC123DEFG',
    teamId: 'TEAM123456',
    bundleId: 'ca.acme.app',
  },
  fcm: { serviceAccountJson: process.env.FCM_SERVICE_ACCOUNT_JSON ?? '' },
})
if (error) throw new Error(error.message)
console.log(pushApp.id, pushApp.apns?.sandbox_status, pushApp.apns?.production_status, pushApp.fcm?.status)

import os

from honkio import Honkio

client = Honkio()  # reads HONKIO_API_KEY

push_app = client.push.apps.create(
    name="Acme mobile",
    apns={
        "key_p8": os.environ.get("APNS_KEY_P8", ""),
        "key_id": "ABC123DEFG",
        "team_id": "TEAM123456",
        "bundle_id": "ca.acme.app",
    },
    fcm={"service_account_json": os.environ.get("FCM_SERVICE_ACCOUNT_JSON", "")},
)
print(push_app["id"], push_app["apns"]["sandbox_status"], push_app["apns"]["production_status"], push_app["fcm"]["status"])

<?php

use Honkio\Honkio;

$honkio = new Honkio(); // reads HONKIO_API_KEY

$pushApp = $honkio->push->apps->create([
    'name' => 'Acme mobile',
    'apns' => [
        'key_p8' => getenv('APNS_KEY_P8') ?: '',
        'key_id' => 'ABC123DEFG',
        'team_id' => 'TEAM123456',
        'bundle_id' => 'ca.acme.app',
    ],
    'fcm' => ['service_account_json' => getenv('FCM_SERVICE_ACCOUNT_JSON') ?: ''],
]);
echo $pushApp['id'], ' ', $pushApp['apns']['sandbox_status'], ' ', $pushApp['apns']['production_status'], ' ', $pushApp['fcm']['status'], PHP_EOL;

Firebase service account (Android)

In the Firebase console, open Project settings, then Service accounts, and generate a new private key. Send the JSON file's text as fcm.service_account_json. Its private key must be the RSA-2048 key Google issues. honkio checks it with a dry run when you upload it and records the project ID.

The service account needs permission to send Firebase Cloud Messaging messages.

Credential health

Each credential is unverified, valid or invalid. A send that Apple or Google accepts marks it valid, and a rejection of the credential itself marks it invalid. An invalid credential is still tried on later sends, so one transient rejection does not block a platform.

When a credential turns invalid, you get one push_app.credentials_invalid webhook for the change. honkio also re-checks invalid or unused credentials daily and emails the account owner when one turns invalid.

Replace a credential with PATCH /v1/push/apps/:id; it is checked again on upload. Credentials are write-only, and apps and their credentials are shared by test and live mode, so creating, changing and deleting an app needs a live key; a test key can read apps and register test devices against them. Credential uploads and changes are limited to 20 an hour per account (429 RATE_LIMITED).