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

# Managed mode

> In managed mode, pgw checks each app's SIP password and keeps the registration at the PBX alive itself.

In the default mode, passthrough, a sleeping app must wake up every time its registration at the PBX is about to expire. That works well with registrations of an hour. With a PBX that grants only a few minutes, pgw has to wake every phone every few minutes. That drains batteries, and the app stays reachable only while every one of those pushes arrives.

In managed mode, pgw registers at the PBX on the user's behalf and renews as often as the PBX wants. The app registers with pgw alone, on a schedule that pgw sets.

## When to use managed mode

| | Passthrough (default) | Managed |
| - | - | - |
| Who checks the app's password | The PBX | pgw |
| Passwords that pgw stores | None | One for each user, encrypted |
| Who keeps the registration at the PBX | The app, woken by refresh pushes | pgw |
| The PBX must support the Path header | Yes, unless the upstream uses `masquerade` | No |

Use managed mode when:

* Your PBX grants short registrations.
* You want to ring all of a user's devices from pgw, with one contact at the PBX.
* Your apps sign in with a token instead of a SIP password.

Stay with passthrough when you don't want SIP passwords stored anywhere except the PBX.

You choose the mode when you create an upstream, and you can't change it afterward.

## How managed mode works

Example Corp moves user `1001` to managed mode. It gives pgw the password for `1001`, which pgw stores encrypted. From then on, the app's registration with pgw and pgw's registration at the PBX are separate:

```mermaid theme={null}
sequenceDiagram
    participant App
    participant pgw
    participant PBX
    App->>pgw: REGISTER
    pgw-->>App: 401 Unauthorized (pgw's challenge)
    App->>pgw: REGISTER with credentials
    pgw->>PBX: REGISTER with pgw's Contact and the stored password
    PBX-->>pgw: 200 OK
    pgw-->>App: 200 OK
    Note over pgw,PBX: pgw renews before each grant expires
```

1. **The app registers with pgw.** pgw sends the digest challenge itself and checks the answer against the stored password. The app uses the same username and password as before.
2. **pgw registers at the PBX.** It sends its own REGISTER, with its own address as the contact and the stored password. The PBX never sees the app's push token.
3. **pgw keeps renewing.** It renews before each grant from the PBX expires, however short the grant is. The app isn't involved.

Calls work as in passthrough mode: the PBX sends the INVITE to pgw, and pgw wakes the app with a call push.

pgw still sends each iOS and Android app a refresh push before the app's own registration with pgw expires, so that pgw knows the device is alive. Against a PBX with short registrations, these pushes are far less frequent than the refresh pushes of passthrough mode. A late one costs no calls, because the registration at the PBX doesn't depend on it.

## One contact for each user, or one for each device

By default, pgw registers one contact at the PBX for each user, however many devices the user has. When a call arrives, pgw rings all of the user's devices at once, and the first one to answer takes the call.

| | `per_user` (default) | `per_device` |
| - | - | - |
| Contacts at the PBX | One for each user | One for each device |
| Who rings the devices | pgw, all at once | The PBX, by its own rules |
| Room needed at the PBX | One free contact for each user | One contact for each device |

Use `per_user` unless a feature of your PBX must act on a single device. To change it, see [Set up managed mode](https://docs.pgw.sipmicro.services/upstreams/set-up-managed-mode.md#choose-how-pgw-registers-devices).

## When pgw removes a device

In managed mode, a registration no longer expires on its own, so pgw decides when a device is gone:

| Case | What pgw does |
| - | - |
| The device hasn't registered for 7 days (`credential_silence_purge`) | Removes it. A live app registers on every refresh push, so normally only an uninstalled app stays silent that long. An app with the refresh push turned off, or a browser app, can also stay silent while it still works. |
| The push service reports that the token is no longer valid | Removes it at once. |
| The device registered without push, such as a desktop softphone, and its connection closed | Removes it within about 5 seconds, because pgw has no way to reach it. |
| The PBX refuses the stored password five times in a row | Removes the user's devices, or the one device with `per_device`. See [Troubleshooting](https://docs.pgw.sipmicro.services/troubleshooting.md#register-gets-502-bad-gateway). |

The user and the stored password stay. A removed device comes back the next time its app registers.

## Settings

| Setting | Default | What it does |
| - | - | - |
| `managed_registration` | `per_user` | One contact at the PBX for each user, or `per_device`. You can override it for one upstream. |
| `managed_refresh_push` | `true` | Whether apps get a refresh push before their registration with pgw expires. You can override it for one app. |
| `managed_renewals_per_second` | `20` | How fast pgw renews at each upstream after a restart, when every registration is due at once. |
| `credential_silence_purge` | `168h` | How long a device can stay silent before pgw removes it. |

## Next steps

> [card] [Set up managed mode](https://docs.pgw.sipmicro.services/upstreams/set-up-managed-mode.md)
>
> Create a managed upstream and add its users.

> [card] [Sign in with a Bearer token](https://docs.pgw.sipmicro.services/upstreams/bearer-tokens.md)
>
> Let apps register with a token from your sign-in service.

> [card] [Kamailio user source](https://docs.pgw.sipmicro.services/pbx/kamailio-user-source.md)
>
> Read the users from Kamailio's database.


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