SapaganDocs sapagan.com

Guides

FCM and APNs credentials

Give Sapagan the keys it needs to send push to Android, iPhone and the web.

Sapagan sends push through Firebase Cloud Messaging (FCM) HTTP v1, for Android, iPhone and browsers. You give each workspace the credentials of your own Firebase project. Staging and production are separate projects, so give each workspace its own.

Only an owner can set credentials, from the console. No API key can.

FCM service account#

  1. In the Firebase console, open Project settings, Service accounts.
  2. Choose "Generate new private key" and download the JSON file.
  3. In the Sapagan console, open Settings, Setup, Push credentials and upload the file.

Sapagan checks the file first: it must be a service_account with a project_id, a client_email and a readable private_key, at most 16 KB. It is stored encrypted for that workspace, and replaces any earlier one. The console never shows it again.

Use "Check" to test it. Sapagan asks FCM for a dry run, which validates the account and delivers nothing. A token error means the project exists and the account may send. PERMISSION_DENIED names the missing role. You may run 10 checks every 10 minutes per workspace.

The console calls PUT /v1/setup/push-credentials/fcm and POST /v1/setup/push-credentials/fcm/check for you. These routes need an owner's console session and are not in the public reference.

Apple Push key (APNs)#

Sapagan reaches iPhones through FCM, so Firebase needs your Apple key too:

  1. In your Apple developer account, create an APNs authentication key (a .p8 file). Note the key id and your team id.
  2. In the Firebase console, open Project settings, Cloud Messaging, and upload the .p8 under your iOS app, with the key id and team id.

Sapagan also accepts the same key on the Setup page (the .p8 text, its 10-character key id and team id, and the app's bundle id). It is stored for a direct APNs channel and is not used for sending yet. Treat the Firebase upload as the step that matters today.

Web push#

Browsers also go through FCM. Add a Web app to the same Firebase project and generate a VAPID key. The VAPID key stays in your Firebase project and your page. See Web.

Tokens you register#

Pass the FCM registration token for iOS as well, not the raw APNs token. When FCM answers that a token is unregistered or invalid, Sapagan marks that device invalid and skips it.

Troubleshooting#

SignLikely cause
503 push_unavailableNo credentials for the workspace.
A message is failed after sendingThe project or service account roles. Run Check.
iPhone gets nothing, Android worksThe Apple key is not uploaded in Firebase.
Nothing arrives in a development workspaceThe person is not on the test list.