> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pushctl.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```text theme={null}
Team
└── Application
    ├── iOS platform ── APNs credential
    ├── Android platform ── FCM credential
    ├── Application tokens
    ├── External users
    │   └── Installations
    └── Notifications
        └── Per-installation deliveries and events
```

## Core concepts

<AccordionGroup>
  <Accordion title="Team" icon="users">
    A team owns applications and provider credentials. Members use roles to control who can change team and application settings.
  </Accordion>

  <Accordion title="Application" icon="mobile-screen">
    An application is the boundary for tokens, installations, users, notifications, and delivery history. One application can serve both iOS and Android.
  </Accordion>

  <Accordion title="External user" icon="user-tag">
    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.
  </Accordion>

  <Accordion title="Installation" icon="smartphone">
    An installation represents one app installation on one device. The client SDK supplies its platform identifier, permission state, and non-sensitive device metadata.
  </Accordion>

  <Accordion title="Provider credential" icon="shield-keyhole">
    APNs and FCM credentials authorize Pushctl to send through Apple or Firebase. They are separate from application tokens.
  </Accordion>

  <Accordion title="Application token" icon="key">
    A bearer token authenticates an SDK or server to one application. Its abilities determine which API operations it can call.
  </Accordion>
</AccordionGroup>

## Notification lifecycle

<Steps>
  <Step title="Queued">Pushctl validates the request and records the target external user IDs.</Step>
  <Step title="Processing">Eligible installations receive individual provider deliveries.</Step>
  <Step title="Accepted or failed">APNs or FCM accepts the push, or returns an error for that installation.</Step>
  <Step title="Received, displayed, opened, or dismissed">A client SDK reports lifecycle events. Event IDs are idempotent, so retries do not inflate counts.</Step>
</Steps>

<Note>
  **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.
</Note>