# pgw > Documentation for pgw, the RFC 8599 push gateway for SIP. - [What is pgw?](https://docs.pgw.sipmicro.services/index.md): pgw is a push notification gateway for SIP. It makes calls ring on mobile and browser softphones that the system has put to sleep. - [Concepts](https://docs.pgw.sipmicro.services/concepts.md): 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. - [How pgw works](https://docs.pgw.sipmicro.services/how-pgw-works.md): Follow a registration, an incoming call, and a missed call through pgw, message by message. - [pgw FAQ](https://docs.pgw.sipmicro.services/faq.md): Answers to common questions about pgw: supported PBXs and apps, passwords and push tokens, restarts, high availability, IPv6, and certificates. - [Get started with pgw](https://docs.pgw.sipmicro.services/quickstart.md): Run pgw on your own computer, connect your PBX and your app to it, and call the app while it is closed. - [Tutorial: Test a real push on the Android emulator](https://docs.pgw.sipmicro.services/tutorial-android-emulator.md): Run pgw and Asterisk on your computer, install a Linphone build in the Android emulator, and receive a call through a real FCM push. - [Security in pgw](https://docs.pgw.sipmicro.services/security.md): What pgw stores and how it protects it, which ports to open, and how pgw stops password guessing. - [Managed mode](https://docs.pgw.sipmicro.services/upstreams/managed-mode.md): In managed mode, pgw checks each app's SIP password and keeps the registration at the PBX alive itself. - [Set up managed mode](https://docs.pgw.sipmicro.services/upstreams/set-up-managed-mode.md): Create a managed upstream, add a user for each SIP account, and manage those users. - [Sign in with a Bearer token](https://docs.pgw.sipmicro.services/upstreams/bearer-tokens.md): Let apps register with a short-lived access token from your sign-in service, so that they never hold a SIP password. - [Serve several SIP domains on one PBX](https://docs.pgw.sipmicro.services/upstreams/several-domains.md): List your customers' SIP domains on one upstream, so that pgw sends registrations for all of them to the same PBX. - [Keep a tenant in a file](https://docs.pgw.sipmicro.services/config-as-code/tenant-file.md): Describe your apps, upstreams, and users in one YAML file, preview each change, and apply it in one step. - [Run a sync in CI](https://docs.pgw.sipmicro.services/config-as-code/sync-in-ci.md): Preview a tenant file change in one pipeline step, and apply it with pgw config sync --yes after a person reviews the preview. - [Settings reference](https://docs.pgw.sipmicro.services/reference/settings.md): Every setting of pgw serve, with its YAML key, environment variable, default, and allowed range. - [The .env file](https://docs.pgw.sipmicro.services/reference/env-file.md): How pgw reads PGW_ variables from the .env file in the folder where you run it, and which source wins when a setting comes from several. - [Configure Asterisk for pgw](https://docs.pgw.sipmicro.services/pbx/asterisk.md): Change the PJSIP settings of each user, so that Asterisk sends that user's calls through pgw. - [Configure FreeSWITCH for pgw](https://docs.pgw.sipmicro.services/pbx/freeswitch.md): Create a masquerade upstream and allow several contacts for each user, so that FreeSWITCH sends calls for your apps through pgw. - [Use a Kamailio user source](https://docs.pgw.sipmicro.services/pbx/kamailio-user-source.md): Have pgw check app passwords against Kamailio's subscriber table in managed mode, so you keep one list of SIP accounts. - [Configure apps for pgw](https://docs.pgw.sipmicro.services/apps/overview.md): Register your mobile or browser app in pgw with its push credentials, and choose how pgw delivers calls to it. - [Integrate your app with pgw](https://docs.pgw.sipmicro.services/apps/integrate.md): Implement the SIP and push handling that a softphone needs to receive calls through pgw while it sleeps. - [Configure an iOS app](https://docs.pgw.sipmicro.services/apps/ios.md): Create an APNs key for your iOS app and register the app in pgw. - [Configure an Android app](https://docs.pgw.sipmicro.services/apps/android.md): Create a Firebase service account for your Android app and register the app in pgw with its Firebase project ID and number. - [Configure a web app](https://docs.pgw.sipmicro.services/apps/web.md): Accept browser apps over secure WebSocket and wake them for calls with Web Push and a VAPID key. - [Use Linphone with pgw](https://docs.pgw.sipmicro.services/apps/linphone.md): Build the open-source Linphone app with your own push credentials, and set up its SIP account to register through pgw. - [Push payload](https://docs.pgw.sipmicro.services/reference/push-payload.md): The events, fields, and delivery settings of each push that pgw sends to iOS, Android, and browser apps. - [Install pgw on a server](https://docs.pgw.sipmicro.services/deploy/install.md): Install the pgw binary on a Linux host, create its user, folders, master key, and bootstrap token, start it, and create the first tenant. - [Run pgw under systemd](https://docs.pgw.sipmicro.services/deploy/systemd.md): Create a systemd unit for pgw, read its log with journalctl, and restart or reload it. - [Install a TLS certificate](https://docs.pgw.sipmicro.services/deploy/tls.md): Give pgw's app listener a certificate from a public certificate authority, reload it without dropping apps, and watch its expiry. - [Release notes](https://docs.pgw.sipmicro.services/release-notes.md): What changed in each pgw release, and the changes that need action when you upgrade. - [Upgrade pgw](https://docs.pgw.sipmicro.services/upgrade.md): Upgrade pgw to a new release, switch managed upstreams to per-user registration, and roll an upgrade back. - [Back up, move, or restore pgw](https://docs.pgw.sipmicro.services/backup-move-restore.md): Back up pgw's data folder and master key, move pgw to another host, and restore it after the host is lost. - [Tune the host for many devices](https://docs.pgw.sipmicro.services/tune-the-host.md): Set the open-file limit, the UDP receive buffer, and the keepalive that pgw depends on when it serves many devices. - [Troubleshooting](https://docs.pgw.sipmicro.services/troubleshooting.md): Find the cause of a failed registration, call, push, TLS connection, or startup in pgw by the status code or log line that you see, and fix it. - [CLI reference](https://docs.pgw.sipmicro.services/reference/cli.md): The pgw commands and flags that run the gateway and manage it through the admin API. - [SIP responses](https://docs.pgw.sipmicro.services/reference/sip-responses.md): The SIP responses that pgw sends itself, the headers it adds, and when it sends each one. - [Database](https://docs.pgw.sipmicro.services/reference/database.md): The tables in pgw's SQLite database, how they relate, how long pgw keeps each row, and which columns hold secrets. - [Check the health of pgw](https://docs.pgw.sipmicro.services/health-checks.md): Use the /healthz and /readyz endpoints on the admin listener for liveness and readiness checks. - [Scrape pgw metrics with Prometheus](https://docs.pgw.sipmicro.services/metrics.md): Scrape the Prometheus metrics that pgw serves on its admin listener, and look up each metric, its type, and its labels. - [Set up alerts for pgw](https://docs.pgw.sipmicro.services/alerts.md): Alert on failing pushes, unreachable PBXs, password guessing, and an expiring certificate with Prometheus rules. - [Read pgw logs](https://docs.pgw.sipmicro.services/logs.md): Read and filter pgw's logs, follow one device or call, and send the logs to a log collector. - [Log SIP messages](https://docs.pgw.sipmicro.services/sip-message-log.md): Turn on the SIP message log to see every SIP message that pgw sends and receives, with its secrets masked. - [Read the push log](https://docs.pgw.sipmicro.services/push-log.md): List the push events that pgw recorded, and set how long pgw keeps them. - [API reference](https://docs.pgw.sipmicro.services/api/introduction.md): Call pgw's admin API: the base URL, JSON bodies, size limits, and the playground on this site. - [Authenticate API requests](https://docs.pgw.sipmicro.services/api/authentication.md): Send a tenant API key with tenant requests, and the bootstrap token with the gateway-wide requests. - [Handle API errors](https://docs.pgw.sipmicro.services/api/errors.md): Read the error body that the admin API returns, and look up the status codes that it uses. - [Page through lists](https://docs.pgw.sipmicro.services/api/pagination.md): Read long lists of bindings and users one page at a time with limit, after, and next. - [Create the first tenant](https://docs.pgw.sipmicro.services/api-reference/tenant/create-the-first-tenant.md): Creates the first tenant and returns its API key. pgw stores only a SHA-256 hash of the key, so this response is the only place that shows the key. The request works once for each database, and needs the server's `PGW_BOOTSTRAP_TOKEN` in `Authorization: Bootstrap `. - [Get the caller's tenant](https://docs.pgw.sipmicro.services/api-reference/tenant/get-the-callers-tenant.md) - [List apps](https://docs.pgw.sipmicro.services/api-reference/apps/list-apps.md): Lists the tenant's apps. pgw never returns their credentials. - [Register an app](https://docs.pgw.sipmicro.services/api-reference/apps/register-an-app.md): Registers an app with its push credentials. iOS apps need the `apns_*` fields, Android apps need the `fcm_*` fields, and web apps need `vapid_subject`. A tenant can have one web app. Without `vapid_private_key_pem`, pgw generates the web app's VAPID key. pgw checks the format of each credential and… - [Change an app's delivery mode or VAPID subject](https://docs.pgw.sipmicro.services/api-reference/apps/change-an-apps-delivery-mode-or-vapid-subject.md): Changes the fields in the body and keeps the others. A web app's VAPID key can't change, because a new key ends every browser subscription. To change it, delete the app and create it again. - [Export a web app's VAPID private key](https://docs.pgw.sipmicro.services/api-reference/apps/export-a-web-apps-vapid-private-key.md): Returns the web app's VAPID private key in PEM, for a backup. Keep it secret: anyone with it can send pushes to the tenant's browsers. - [List upstreams](https://docs.pgw.sipmicro.services/api-reference/upstreams/list-upstreams.md) - [Add a PBX](https://docs.pgw.sipmicro.services/api-reference/upstreams/add-a-pbx.md): Adds a PBX that pgw registers apps with. pgw finds the upstream for a REGISTER by the host of its request URI: an upstream whose `host` or one of whose `domains` equals it, else the upstream with the longest `*.` wildcard in `domains` that matches it. Each host and domain belongs to one upstream acr… - [Delete an upstream](https://docs.pgw.sipmicro.services/api-reference/upstreams/delete-an-upstream.md): Deletes an upstream that no binding uses. Bindings end when their registration expires, at most `max_expires` seconds, or the PBX's minimum when that is longer, after the app last registered. With `force=true`, pgw deletes the upstream and its bindings together. pgw can't unregister them at the PBX,… - [Change an upstream](https://docs.pgw.sipmicro.services/api-reference/upstreams/change-an-upstream.md): Changes the fields in the body and keeps the others. The host can't change: delete the upstream and create it again. pgw applies a new `invite_source_cidrs` and new `domains` at once. pgw returns `400` for a `transport` other than `udp` or `tcp`, and for an empty `invite_source_cidrs` on an upstream… - [List an upstream's users](https://docs.pgw.sipmicro.services/api-reference/users/list-an-upstreams-users.md): Lists the upstream's users by domain, then username, one page at a time. To get the next page, pass the response's `next` as `after`. - [Add a user to an upstream](https://docs.pgw.sipmicro.services/api-reference/users/add-a-user-to-an-upstream.md): Stores a SIP account for managed mode. pgw encrypts the password with the tenant's data key and never returns it. - [Drop a user's registrations](https://docs.pgw.sipmicro.services/api-reference/users/drop-a-users-registrations.md): Removes the user's registrations on a managed upstream at once, so the user's devices get no more calls, and unregisters them at the PBX. The user stays as it is: a device that registers again with the right password registers. To keep a Kamailio subscriber out, block it in Kamailio's database first… - [Delete a user](https://docs.pgw.sipmicro.services/api-reference/users/delete-a-user.md): Deletes the user. pgw removes its devices' managed bindings at once, and their registrations at the PBX. - [Change a user's password or auth username, or turn it on or off](https://docs.pgw.sipmicro.services/api-reference/users/change-a-users-password-or-auth-username-or-turn-it-on-or-off.md): Changes the fields in the body. When you turn a user off, pgw removes its devices' managed bindings at once, and their registrations at the PBX. - [List registered devices](https://docs.pgw.sipmicro.services/api-reference/bindings/list-registered-devices.md): Lists the tenant's live bindings in key order, one page at a time. pgw never returns push tokens. To get the next page, pass the response's `next` as `after`. - [Delete a registered device](https://docs.pgw.sipmicro.services/api-reference/bindings/delete-a-registered-device.md): Removes the binding. On a managed mode upstream, pgw also removes the device's registration at the PBX. On a passthrough mode upstream, the PBX keeps the registration until it expires, and pgw answers its calls to the device with `404` meanwhile. The app registers again on its next REGISTER. - [Send a device a silent test push](https://docs.pgw.sipmicro.services/api-reference/bindings/send-a-device-a-silent-test-push.md): Sends the device a silent push with `pgw_event` `test`, and returns the push service's answer, so you can check the device's push token. On iOS the push goes to the remote token as a background push. The app shows nothing. A test push counts toward `call_push_rate_per_binding`, and pgw records it as… - [List recent push attempts](https://docs.pgw.sipmicro.services/api-reference/push-events/list-recent-push-attempts.md): Lists the tenant's newest push attempts, newest first. - [Load the certificate again](https://docs.pgw.sipmicro.services/api-reference/tls/load-the-certificate-again.md): Loads the certificate and key files of the app listener again, so a renewed certificate takes effect without a restart. Connections that are already open keep the certificate they started with. The certificate belongs to the whole gateway, so the endpoint needs the server's `PGW_BOOTSTRAP_TOKEN`, no… - [List the active REGISTER bans](https://docs.pgw.sipmicro.services/api-reference/register-bans/list-the-active-register-bans.md): Lists the source addresses that pgw refuses REGISTERs from, because the PBX, or pgw in managed mode, refused too many of their credentials. A ban covers every tenant behind an address, so the endpoint needs the server's `PGW_BOOTSTRAP_TOKEN`, not a tenant API key. - [Lift a REGISTER ban](https://docs.pgw.sipmicro.services/api-reference/register-bans/lift-a-register-ban.md): Ends the ban of a source address and clears its count of refused credentials. An IPv6 address lifts the ban of its /64 prefix. - [Export the tenant's configuration](https://docs.pgw.sipmicro.services/api-reference/config/export-the-tenants-configuration.md): Returns the tenant's apps, upstreams, and managed mode users as a snapshot that `POST /config/sync` accepts. Apps are sorted by platform and bundle ID, upstreams by host, and each upstream's users by domain, then username. pgw returns no secret: it leaves out `apns_key_pem`, `fcm_service_account_jso… - [Make the tenant's configuration match a snapshot](https://docs.pgw.sipmicro.services/api-reference/config/make-the-tenants-configuration-match-a-snapshot.md): Plans the changes that make the tenant's apps, upstreams, and managed mode users match `snapshot`, and applies them in one transaction. pgw stores either every change or none. ## OpenAPI Specs - [openapi](/reference/openapi.yaml) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.