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

# Make the tenant's configuration match a snapshot

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

pgw matches an app by platform and bundle ID, an upstream by host,
and a user by upstream host and username. A field that the snapshot
leaves out takes the default of a create request. An empty secret
keeps the stored one. A change names the fields that change, and
names a changed secret without its value. Without `prune`, pgw
deletes nothing. With `prune`, it deletes the records that the
snapshot leaves out, and `devices` counts the bindings that each
delete removes. pgw deletes an upstream's users with it. pgw never
compares or deletes the users of an upstream with
`user_source: kamailio`.

With `dry_run`, pgw returns the plan and its digest and changes
nothing. When a plan deletes anything, an apply must send the
`plan_digest` of the dry run, and pgw answers `409` when the plan
changed since then. pgw answers `409`, also for a dry run, when
the snapshot gives an upstream a host or a domain that another
tenant uses. pgw answers `400` when it gives one host or domain to
two of the tenant's upstreams. A domain can move from one upstream
to another in one sync. pgw checks the database of each new Kamailio
upstream, and of each upstream whose Kamailio settings or password
change, before it plans to store them.

The body can be up to 16 MiB.




## OpenAPI

````yaml /reference/openapi.yaml post /config/sync
openapi: 3.1.0
info:
  title: pgw admin API
  version: 0.4.0
  description: |
    Manage a pgw tenant: its apps, upstreams, managed mode users, bindings,
    and push log.

    The API listens on `admin_listen`, `127.0.0.1:8080` by default, over plain
    HTTP. Every endpoint except `POST /bootstrap`, `POST /tls/reload`, and the
    register bans needs a tenant API key in the `Authorization` header. Those
    need the server's `PGW_BOOTSTRAP_TOKEN`. Request bodies are JSON objects
    of at most 1 MiB, or 16 MiB for `POST /config/sync`, and pgw rejects
    unknown fields. Responses are never cached.

    An unknown path gets `404`, and a method that the path doesn't serve gets
    `405` with an `Allow` header. Every `GET` endpoint also answers `HEAD`.
    An endpoint that needs an API key answers `500` when pgw can't check the
    key.

    The same listener also serves `GET /metrics`, `GET /healthz`, and
    `GET /readyz`, outside `/api/v1` and without authentication. The health
    checks and metrics pages describe them.
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - url: '{baseUrl}'
    description: Your pgw admin listener
    variables:
      baseUrl:
        default: http://127.0.0.1:8080/api/v1
        description: The address of admin_listen, followed by /api/v1.
  - url: http://localhost:8080/api/v1
    description: pgw on this computer
security:
  - apiKey: []
tags:
  - name: Tenant
    description: Create the first tenant and read the caller's tenant.
  - name: Apps
    description: Mobile and web apps and their push credentials.
  - name: Upstreams
    description: PBXs that pgw registers apps with.
  - name: Users
    description: >-
      SIP accounts that pgw checks itself and registers at the PBX in managed
      mode.
  - name: Bindings
    description: Devices registered through pgw.
  - name: Push events
    description: The log of push attempts.
  - name: TLS
    description: The certificate that pgw presents to apps.
  - name: Register bans
    description: >-
      Source addresses that pgw refuses REGISTERs from after too many refused
      credentials.
  - name: Config
    description: Export a tenant's configuration and make it match a snapshot.
paths:
  /config/sync:
    post:
      tags:
        - Config
      summary: Make the tenant's configuration match a snapshot
      description: |
        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.

        pgw matches an app by platform and bundle ID, an upstream by host,
        and a user by upstream host and username. A field that the snapshot
        leaves out takes the default of a create request. An empty secret
        keeps the stored one. A change names the fields that change, and
        names a changed secret without its value. Without `prune`, pgw
        deletes nothing. With `prune`, it deletes the records that the
        snapshot leaves out, and `devices` counts the bindings that each
        delete removes. pgw deletes an upstream's users with it. pgw never
        compares or deletes the users of an upstream with
        `user_source: kamailio`.

        With `dry_run`, pgw returns the plan and its digest and changes
        nothing. When a plan deletes anything, an apply must send the
        `plan_digest` of the dry run, and pgw answers `409` when the plan
        changed since then. pgw answers `409`, also for a dry run, when
        the snapshot gives an upstream a host or a domain that another
        tenant uses. pgw answers `400` when it gives one host or domain to
        two of the tenant's upstreams. A domain can move from one upstream
        to another in one sync. pgw checks the database of each new Kamailio
        upstream, and of each upstream whose Kamailio settings or password
        change, before it plans to store them.

        The body can be up to 16 MiB.
      operationId: syncConfig
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SyncRequest'
            example:
              snapshot:
                apps:
                  - platform: android
                    bundle_id: com.example.phone
                    fcm_project_id: example-phone
                upstreams:
                  - name: Main PBX
                    host: pbx.example.com
                    mode: managed
                    invite_source_cidrs:
                      - 203.0.113.10/32
                    users:
                      - username: '1001'
              prune: true
              dry_run: true
      responses:
        '200':
          description: The plan, and whether pgw applied it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyncResponse'
              example:
                changes:
                  - op: update
                    kind: app
                    key: android/com.example.phone
                    fields:
                      - fcm_service_account_json
                  - op: delete
                    kind: upstream
                    key: old.example.com
                    devices: 3
                plan_digest: >-
                  9f2c4e0b7a1d3f5e6c8b9a0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f
                applied: false
        '400':
          description: |
            The body isn't valid, a record in the snapshot isn't valid, or a
            Kamailio database check failed. The message names the record by
            its key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: >-
                  invalid request: upstream pbx.example.com: mode cannot change;
                  delete the upstream and create it again
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: |
            The plan deletes and `plan_digest` is missing or isn't the plan's,
            or an upstream host or domain in the snapshot overlaps a name of
            another tenant.
            pgw changed nothing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: plan changed; run sync again
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    SyncRequest:
      type: object
      additionalProperties: false
      required:
        - snapshot
      properties:
        snapshot:
          $ref: '#/components/schemas/Snapshot'
        prune:
          type: boolean
          default: false
          description: |
            Delete the records that the snapshot leaves out, within the
            lists that it sends. A `null` or missing list deletes nothing.
        dry_run:
          type: boolean
          default: false
          description: Return the plan and change nothing.
        plan_digest:
          type: string
          description: The `plan_digest` of the dry run. Required when the plan deletes.
    SyncResponse:
      type: object
      required:
        - changes
        - plan_digest
        - applied
      properties:
        changes:
          type: array
          items:
            $ref: '#/components/schemas/Change'
        plan_digest:
          type: string
          description: |
            Identifies the plan. It doesn't depend on the order of the
            changes or on their `devices`.
        applied:
          type: boolean
          description: Whether pgw stored the changes.
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: What went wrong. Never contains the values that you sent.
    Snapshot:
      type: object
      required:
        - apps
        - upstreams
      description: >
        A tenant's configuration. The records use the fields of the create

        requests, except that a secret can be empty, which keeps the stored

        one. A `null` list leaves its records alone, even with `prune`. An empty
        list names the section with no records,

        so `prune` deletes every record of that kind. An export always

        sends `apps`, `upstreams`, and the `users` of each upstream whose

        users pgw stores.
      properties:
        apps:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/CreateAppRequest'
        upstreams:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/SnapshotUpstream'
    Change:
      type: object
      required:
        - op
        - kind
        - key
      properties:
        op:
          type: string
          enum:
            - create
            - update
            - delete
        kind:
          type: string
          enum:
            - app
            - upstream
            - user
        key:
          type: string
          description: |
            The record's natural key: `platform/bundle_id` for an app, the
            host for an upstream, and `host/username` for a user, or
            `host/username@domain` for a user of an upstream with domains.
          example: pbx.example.com/1001
        fields:
          type: array
          description: The fields that an update changes. A secret is named, never shown.
          items:
            type: string
        devices:
          type: integer
          description: The bindings that a delete removes.
    CreateAppRequest:
      type: object
      additionalProperties: false
      required:
        - platform
        - bundle_id
      properties:
        platform:
          type: string
          enum:
            - ios
            - android
            - web
        bundle_id:
          type: string
          description: >-
            The iOS bundle ID or the Android package name. For a web app, any
            label.
        name:
          type: string
          maxLength: 64
          description: >-
            A name for the app, which log lines show. Without one, log lines
            show the bundle ID. Up to 64 characters, with no control characters.
        apns_team_id:
          type: string
          description: The Apple team ID. Required for iOS.
        apns_key_id:
          type: string
          description: The APNs key ID. Required for iOS.
        apns_key_pem:
          type: string
          description: The contents of the APNs `.p8` key, a PKCS
          writeOnly: true
        apns_environment:
          type: string
          enum:
            - production
            - sandbox
          default: production
          description: Use `sandbox` for builds from Xcode.
        fcm_project_id:
          type: string
          description: >-
            The Firebase project ID. pgw sends pushes to this project. Required
            for Android. Must not be all digits.
        fcm_project_number:
          type: string
          pattern: ^[0-9]*$
          description: >-
            The Firebase project number. Optional, but Linphone identifies its
            project by this number, so a Linphone build needs it.
        fcm_service_account_json:
          type: string
          description: >-
            The contents of the Firebase service account key file. Required for
            Android.
          writeOnly: true
        vapid_subject:
          type: string
          description: >-
            A `mailto:` or `https:` URI that push services can use to contact
            you. Required for web.
        vapid_private_key_pem:
          type: string
          description: A P-256 private key in PEM, PKCS
          writeOnly: true
        delivery_mode:
          $ref: '#/components/schemas/DeliveryMode'
          description: Omit to use the gateway default.
        managed_refresh_push:
          type: string
          enum:
            - ''
            - 'on'
            - 'off'
          description: >-
            Whether pgw sends the app's managed iOS and Android devices a
            refresh push before their registration expires. Omit to use the
            gateway default.
    SnapshotUpstream:
      type: object
      additionalProperties: false
      required:
        - name
        - host
      description: |
        An upstream with its managed mode users beside its fields. The
        fields are those of `CreateUpstreamRequest`, except that
        `kamailio.password` can be left out, which keeps the stored one.
      properties:
        name: 472a7436-d1d6-4b6c-adcc-3c930bb2479b
        host: 8c8a87ed-6cd8-4aef-81b7-421735665273
        domains: fe1356b8-1ab0-489a-a342-5c02eac2c868
        port: 7f210873-e327-4693-9643-79eff2a203bd
        transport: ba89af5b-94dd-4333-a496-89046a6aab7e
        max_expires: 36acbfee-1138-476e-85d2-40b420c45dfe
        invite_source_cidrs: fd549961-b3ac-40bf-97a0-0d7313c62007
        strict_path: 9b9d54e7-1545-40ff-98ae-26d9f55f538f
        mode: 359b82d2-e748-4fd9-9eaf-5e76d5a54285
        keepalive_seconds: 5ad5094c-b9ae-41a6-80b4-298282a2ff49
        realm: cadcc87a-cf83-4a7c-946a-8488a79e04d3
        managed_registration: 884a5fa5-20c0-459f-9ef6-5cd17efc35df
        contact_strategy: 73da0495-27cc-4a89-adc7-d3080fae39ed
        user_source: f24beda4-3593-48bb-8b48-8ca893b186e4
        kamailio: d123f8d7-4bed-4956-90bf-14b8792ff7ed
        app_auth: 43e4cd2b-be29-429a-9eb3-4ba3cefdab93
        bearer: 49b650ef-2559-4f6b-b808-06c08d54c9ad
        users:
          type:
            - array
            - 'null'
          description: |
            The upstream's users. Not allowed with `user_source: kamailio`.
            When `null` or left out, `prune` leaves the upstream's users
            alone.
          items:
            $ref: '#/components/schemas/SnapshotUser'
    DeliveryMode:
      type: string
      enum:
        - provisional
        - always_push
      description: |
        How pgw sends a call to an app that has an open connection.
        `provisional` sends the call on the connection and pushes if the app
        doesn't respond within `provisional_timeout`. `always_push` pushes for
        every call.
    SnapshotUser:
      type: object
      additionalProperties: false
      required:
        - username
      description: |
        A managed mode user in a snapshot. The fields are those of
        `CreateUserRequest`, except that `password` can be left out, which
        keeps the stored one. A new user needs a password.
      properties:
        username: 55423089-e547-430b-9dc9-94c350de4c70
        domain: 0d549928-82bc-4cc9-9c4c-0d880a355113
        auth_username: 3a0a6102-69f7-4f16-a406-a6d17655e27e
        password: e58d2491-2eeb-458e-8610-0ca8d179fcb1
        enabled: dd830a7d-4f5c-40b0-a0eb-6bf0426593c0
  responses:
    Unauthorized:
      description: The API key is missing or unknown.
      headers:
        WWW-Authenticate:
          schema:
            type: string
            const: Bearer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: missing or unknown API key
    InternalError:
      description: pgw failed to complete the request. The details are in pgw's log.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: internal error
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: The tenant API key that `POST /bootstrap` returned.

````

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