How Pushctl works

Understand Pushctl teams, applications, provider credentials, users, installations, and delivery events.

Pushctl separates access to the dashboard from access to an application API. This keeps team membership, provider secrets, and runtime integrations independently manageable.

Team
└── Application
    ├── iOS platform ── APNs credential
    ├── Android platform ── FCM credential
    ├── Application tokens
    ├── External users
    │   └── Installations
    └── Notifications
        └── Per-installation deliveries and events

Core concepts

Team

A team owns applications and provider credentials. Members use roles to control who can change team and application settings.

Application

An application is the boundary for tokens, installations, users, notifications, and delivery history. One application can serve both iOS and Android.

External user

An external user ID is a stable identifier from your own system. One user can have multiple installations. Pushctl targets users and fans a notification out to each eligible installation.

Installation

An installation represents one app installation on one device. The client SDK supplies its platform identifier, permission state, and non-sensitive device metadata.

Provider credential

APNs and FCM credentials authorize Pushctl to send through Apple or Firebase. They are separate from application tokens.

Application token

A bearer token authenticates an SDK or server to one application. Its abilities determine which API operations it can call.

Notification lifecycle

1. Queued

   Pushctl validates the request and records the target external user IDs.
2. Processing

   Eligible installations receive individual provider deliveries.
3. Accepted or failed

   APNs or FCM accepts the push, or returns an error for that installation.
4. Received, displayed, opened, or dismissed

   A client SDK reports lifecycle events. Event IDs are idempotent, so retries do not inflate counts.

Accepted is a provider outcome. It does not guarantee that a person saw the notification. Use SDK-reported Displayed and Opened events for that distinction.