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

# Concepts

> The three records that you create in pgw, the one that pgw creates for you, and the two choices that you make for each PBX.

This page follows one user through pgw. Example Corp runs a PBX at `pbx.example.com` and gives its staff an iOS app, `com.example.phone`. User `1001` misses calls whenever the phone is locked, so Example Corp installs pgw at `pgw.example.com`.

To make the phone ring, Example Corp creates three records. pgw adds a fourth when the app registers.

```mermaid theme={null}
flowchart LR
    T[Tenant<br/>Example Corp] --> A[App<br/>com.example.phone]
    T --> U[Upstream<br/>pbx.example.com]
    A -.-> B[Binding<br/>1001 on one iPhone]
    U -.-> B
```

## Records that you create

### Tenant

A tenant is your workspace in pgw. It owns your apps and upstreams, and it has the API key that your commands and API requests use.

You create the tenant once, with `pgw bootstrap`, right after pgw starts for the first time.

### App

An app record gives pgw what it needs to push to one of your apps: the app's identifier and your push credentials for it. Example Corp creates one app record for `com.example.phone`, with the APNs key from its Apple developer account. pgw encrypts the key before it stores it.

You create one app record for each platform that you ship:

| Platform | pgw identifies the app by | Credentials |
| - | - | - |
| iOS | The bundle ID | An APNs key from your Apple developer account. See [iOS apps](https://docs.pgw.sipmicro.services/apps/ios.md). |
| Android | The Firebase project that the app belongs to | A Firebase service account. See [Android apps](https://docs.pgw.sipmicro.services/apps/android.md). |
| Web | One web app for each tenant | A VAPID key, which pgw generates for you. See [Web apps](https://docs.pgw.sipmicro.services/apps/web.md). |

### Upstream

An upstream tells pgw about one of your PBXs. When an app registers, pgw reads the SIP domain in the request and sends the registration to the upstream that owns that domain.

Most setups need one upstream. Example Corp creates one for `pbx.example.com`, so every registration for `1001@pbx.example.com` goes to that PBX.

An upstream also lists the addresses that the PBX sends calls from. pgw accepts calls from those addresses and refuses them from anywhere else.

An upstream also has a [mode](#mode) and a [contact strategy](#contact-strategy), which you choose when you create it. The defaults suit most PBXs.

## The record that pgw creates

### Binding

A binding is one registered device. When user `1001` signs in on an iPhone, the app registers through pgw, and pgw creates a binding that ties together three things:

* The SIP account, `sip:1001@pbx.example.com`.
* The device's push token, which the app sent in its REGISTER.
* The device's registration at the PBX.

When a call for `1001` arrives, the binding tells pgw which device to wake and where to deliver the call. If `1001` also signs in on a tablet, that is a second binding, and both devices ring.

You never create a binding. pgw removes a binding when the app unregisters, when its registration expires, when you delete it, or when Apple or Google reports that the push token is no longer valid.

## Choices for each upstream

You make both choices when you create the upstream, and you can't change them afterward. To change one, delete the upstream and create it again.

### Mode

The mode decides who checks the SIP password, and who keeps the device registered at the PBX.

| | Passthrough (default) | Managed |
| - | - | - |
| Who checks the password | The PBX. pgw passes the challenge and the answer along and never sees the password. | pgw. You give pgw each user's password, which it stores encrypted. |
| Who keeps the registration alive | The app. Before the registration expires, pgw sends a silent push, and the app wakes and registers again. | pgw. It renews at the PBX itself, so the app wakes far less often. |

Start with passthrough. It needs no user records, and your PBX stays the only system that holds passwords.

Choose managed mode when your PBX grants only short registrations, because waking every app every few minutes drains batteries. Managed mode needs each SIP account's password, either as a user record in pgw or from a Kamailio database. See [Managed mode](https://docs.pgw.sipmicro.services/upstreams/managed-mode.md).

### Contact strategy

The contact strategy decides how the PBX learns to send a device's calls to pgw.

| Strategy | What the PBX stores | Use it when |
| - | - | - |
| `path` (default) | The app's own contact, plus a Path header that names pgw. Path is the standard way (RFC 3327) for a proxy to say "send this device's calls through me". | Your PBX supports Path. |
| `masquerade` | pgw's address as the contact. | Your PBX ignores Path. Managed mode always uses it. |

The page for your PBX says which one to use.

## Call delivery settings

These settings control what happens between the PBX's INVITE and the phone ringing. Set them in `config.yaml`. The defaults work for most setups.

| Setting | Default | What it does |
| - | - | - |
| `hold_seconds` | `30` | How long pgw holds a call while the app wakes. After that, pgw answers the PBX with `480 Temporarily Unavailable` and sends the app a missed-call push. |
| `delivery_mode` | `provisional` | What pgw does when the app still has an open connection. With `provisional`, pgw tries that connection first and pushes only if the app stays silent. With `always_push`, pgw pushes for every call. You can override it for one app. |
| `provisional_timeout` | `3s` | How long pgw waits on the open connection before it pushes. |
| `max_bindings_per_aor` | `10` | How many devices one SIP account can register. |

For every setting, see the [settings reference](https://docs.pgw.sipmicro.services/reference/settings.md).

## Next steps

> [card] [Quickstart](https://docs.pgw.sipmicro.services/quickstart.md)
>
> Create these records on your own computer and make a test call.

> [card] [How pgw works](https://docs.pgw.sipmicro.services/how-pgw-works.md)
>
> Follow the SIP messages of a registration and a call.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.