Push Setup (APNs + FCM)

Amba stores your APNs and FCM credentials encrypted, then loads them at send time. You configure them once per project; the rest is automatic.

What you need

iOS (APNs)

1. An APNs Auth Key (.p8) from Apple Developer → Keys → +, scope Apple Push Notifications service.
2. The key's Key ID (10 characters, shown next to the key).
3. Your Team ID (top right of Apple Developer).
4. The app's bundle identifier (e.g. com.example.todoapp).

Android (FCM)

1. A Firebase project linked to your app's package name.
2. A service-account JSON with the Firebase Cloud Messaging API permission (Firebase console → Project settings → Service accounts → Generate new private key).

Configure via MCP (recommended)

amba_configure_integration({
  project_id: "proj_xxx",
  provider: "apns",
  config: {
    key_id: "ABC123DEFG",
    team_id: "TEAM123456",
    bundle_id: "com.example.todoapp",
    apns_key_p8: "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
    environment: "sandbox"
  }
})

amba_configure_integration({
  project_id: "proj_xxx",
  provider: "fcm",
  config: {
    service_account_json: "{ ...the full Firebase service-account JSON... }"
  }
})

Configure via the Admin API

POST /admin/integrations
Authorization: Bearer <developer access token>
 
{
  "provider": "apns",
  "config": {
    "key_id": "ABC123DEFG",
    "team_id": "TEAM123456",
    "bundle_id": "com.example.todoapp",
    "apns_key_p8": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
    "environment": "sandbox"
  }
}

Use "environment": "sandbox" for development / TestFlight / Xcode builds, and "production" for App Store releases. The server rejects sandbox tokens against the production APNs endpoint (and vice versa), so this flag matters.

Verify credentials

Once stored, trigger a POST /admin/integrations/:provider/test to validate credentials against the live provider before you try a real send:

POST /admin/integrations/apns/test
Authorization: Bearer <developer access token>

Response on success:

{ "data": { "provider": "apns", "valid": true } }

For APNs and FCM the test path deliberately sends to an invalid token — a 400-class response proves the credentials themselves are good. A 401 / 403 from the provider surfaces as { valid: false }. An infra-level failure (malformed PEM, credential load error) returns 502 CREDENTIAL_LOAD_FAILED so you can tell a bad key from a bad environment.

Register device tokens

Tokens come from the platform SDK. In Expo:

import { Amba } from '@amba/expo';
 
// Automatic — if you left `autoRegisterPushToken` on the default true,
// the token is registered during Amba.init(). To do it manually:
const result = await Amba.registerPushToken();
// result is { token, platform } or null (permission denied / simulator / unsupported)

Under the hood the client SDK calls:

await client.push.registerToken(token, 'ios'); // or 'android'
// POST /client/push/tokens

Platform must be 'ios' or 'android'. The server infers the provider (apns / fcm) from the platform.

Send a test push

End-to-end validation — this sends a real notification through the same pipeline campaigns use.

POST /admin/push/test
 
{
  "title": "Test push",
  "body": "If you see this, push works.",
  "app_user_id": "<uuid>"
}

Or target an explicit token:

{
  "title": "Test push",
  "body": "...",
  "device_token": "abc123...",
  "provider": "apns"
}

On success you get { data: { sent: true, delivery_id, provider, provider_message_id } }. Provider-side failures surface as 502 with error.details.invalid_token so you can mark dead tokens.

Expo config plugin

You also need the iOS aps-environment entitlement. The @amba/expo config plugin handles it:

{
  "expo": {
    "plugins": [["@amba/expo", { "ios": { "pushNotifications": true } }]]
  }
}

Rebuild native after changing app.json (npx expo prebuild or npx expo run:ios). Push on iOS requires a development build — Expo Go cannot add custom entitlements.

Routes reference

Database tables

Next

• Campaigns — create + send targeted pushes.
• Scheduling — cron, delay, and delivery windows.