Mach Push sends directly through APNs and FCM. The mobile SDK stores only the Mach project ID in the app, while APNs keys and Firebase service-account JSON files stay encrypted in Mach credentials.

Mobile setup

mach push setup

mach credentials

Use `mach push setup` once to install and wire the SDK. Then use `mach credentials` and choose **Push Notifications** to generate or upload APNs credentials, or upload an FCM provider credential. APNs credentials can be saved to all environments or only development, preview, or production. FCM uses one app-scoped credential for the selected Android package across every environment.

Flutter setup installs mach_push_flutter, creates generated public configuration plus an application-owned callback file, injects one non-blocking startup call into main(), and re-registers rotated push tokens. Re-running setup refreshes generated config without replacing the application callbacks.

Where Credentials Live

iOS

Credentials → iOS → bundle identifier → Service credentials → Apple Push Notifications.

Android

Credentials → Android → package name → Service credentials → Firebase Cloud Messaging.

CLI

Run mach credentials, choose the platform, then choose Push Notifications.

Firebase service-account setup

Use the server credential—not google-services.json

Mach needs a Firebase Admin SDK service-account JSON containing a private key. Android's google-services.json is public client configuration and cannot authorize FCM delivery.

Confirm the Firebase project

In Firebase Console, open the project, then go to Project settings → General → Your apps. Confirm the Android package name matches the package selected in Mach Credentials. If the app already has google-services.json, its project_info.project_id must match the Firebase Project ID; use that file only to identify the project—do not upload it to Mach.

Open Firebase project settings

Confirm FCM HTTP v1

Open Project settings → Cloud Messaging. Under Firebase Cloud Messaging API (V1), confirm the API is enabled. Mach sends through the HTTP v1 API, not the retired legacy server-key API.

Open Cloud Messaging settings

Generate the private key

From the same project, open Project settings → Service accounts → Firebase Admin SDK. Click Generate new private key, then confirm Generate key. Your browser downloads the JSON immediately; Google will not show that private key again.

Open Firebase Admin SDK keys

Verify the downloaded file

Open the file only to inspect its field names. It must be valid JSON, its project_id must match step 1, and it must include these server-credential fields:

Expected shape — never paste the real key into source code

{

"type": "service_account",

"project_id": "your-firebase-project-id",

"private_key": "-----BEGIN PRIVATE KEY-----…",

"client_email": "…@….iam.gserviceaccount.com"

}

View Google's service-account key reference

Upload it to Mach

Open Credentials → Android → your package → Service credentials → Firebase Cloud Messaging. Choose the downloaded JSON and save. This single credential is used for the selected Android package across development, preview, and production. Before Save, Mach checks the file and shows only its Project ID, service-account email, and Key ID. Mach encrypts the secret before storage and never returns the private key from the API.

Open Mach Credentials

If something blocks you

Generate key is missing or disabled

Ask a project administrator for Service Account Key Admin access (roles/iam.serviceAccountKeyAdmin). An organization policy may also prohibit JSON key creation.

Mach rejects the JSON

Check that type is "service_account" and that project_id, private_key, and client_email exist. A google-services.json file does not contain these fields.

FCM returns a permission error

Confirm the project matches, FCM API (V1) is enabled, and the service account has Firebase Cloud Messaging API Admin access (roles/firebasecloudmessaging.admin).

A new key fails immediately

Google notes that a newly created key can need about a minute before it works. Wait briefly, then retry the test before replacing it.

Testing

After credentials are uploaded, create one new native build and open it on a device. Expo Go cannot load the Mach native push module.

Send a test

mach push send --user user_123 --title "Hello" --body "Mach Push is ready"

mach push status --days 30

`Provider accepted` means APNs or FCM accepted the notification; it is not an open/read receipt. Mach does not store notification title, message body, or per-message history.

Web hosting

Store submission