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

# Add a PBX

> 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 across the whole pgw install, and no host or
domain can equal, fall under, or cover a name of another tenant,
including a domain in its Kamailio domain table. pgw stores
hosts and domains in canonical form: a DNS name in lower case, or an
IP address without brackets.

pgw returns `400` when `transport` isn't `udp` or `tcp`, when
`host` is a DNS name and `invite_source_cidrs` is empty, and when
an upstream whose users come from Kamailio has `domains`.




## OpenAPI

````yaml /reference/openapi.yaml post /upstreams
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:
  /upstreams:
    post:
      tags:
        - Upstreams
      summary: Add a PBX
      description: |
        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 across the whole pgw install, and no host or
        domain can equal, fall under, or cover a name of another tenant,
        including a domain in its Kamailio domain table. pgw stores
        hosts and domains in canonical form: a DNS name in lower case, or an
        IP address without brackets.

        pgw returns `400` when `transport` isn't `udp` or `tcp`, when
        `host` is a DNS name and `invite_source_cidrs` is empty, and when
        an upstream whose users come from Kamailio has `domains`.
      operationId: createUpstream
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUpstreamRequest'
            examples:
              passthrough:
                summary: Passthrough PBX
                value:
                  name: asterisk
                  host: pbx.example.com
                  domains:
                    - '*.example.com'
                  invite_source_cidrs:
                    - 203.0.113.10/32
              managed:
                summary: Managed PBX with bearer tokens
                value:
                  name: Main PBX
                  host: 192.0.2.10
                  domains:
                    - acme.example.com
                  transport: tcp
                  mode: managed
                  managed_registration: per_user
                  app_auth: both
                  bearer:
                    issuer: https://auth.example.com/
                    audience: pgw
                    jwks_url: https://auth.example.com/.well-known/jwks.json
              kamailio:
                summary: Managed PBX whose users come from Kamailio
                value:
                  name: Kamailio
                  host: sip.example.net
                  invite_source_cidrs:
                    - 198.51.100.0/24
                  mode: managed
                  user_source: kamailio
                  kamailio:
                    driver: mysql
                    host: db.example.net
                    user: pgw_reader
                    password: example-password
                    database: kamailio
      responses:
        '201':
          description: The upstream was created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Upstream'
              examples:
                passthrough:
                  summary: Passthrough PBX
                  value:
                    id: Ux9cT4mK7pLw2RvN5yQs8g
                    name: asterisk
                    host: pbx.example.com
                    domains:
                      - '*.example.com'
                    port: 5060
                    transport: udp
                    mode: passthrough
                    contact_strategy: path
                    max_expires: 3600
                    invite_source_cidrs:
                      - 203.0.113.10/32
                    strict_path: true
                    keepalive_seconds: 30
                    managed_registration: ''
                    user_source: pgw
                    app_auth: digest
                    created_at: '2026-11-02T08:30:00Z'
                managed:
                  summary: Managed PBX with bearer tokens
                  value:
                    id: Rf8pZ3kW6nQv1TmX4cLs7A
                    name: Main PBX
                    host: 192.0.2.10
                    domains:
                      - acme.example.com
                    port: 5060
                    transport: tcp
                    mode: managed
                    contact_strategy: masquerade
                    max_expires: 3600
                    invite_source_cidrs: []
                    strict_path: true
                    keepalive_seconds: 30
                    managed_registration: per_user
                    user_source: pgw
                    app_auth: both
                    bearer:
                      issuer: https://auth.example.com/
                      audience: pgw
                      jwks_url: https://auth.example.com/.well-known/jwks.json
                    created_at: '2026-11-02T08:31:00Z'
                kamailio:
                  summary: Managed PBX whose users come from Kamailio
                  value:
                    id: Km3wQ8zT1nVr6YpL4xCs9A
                    name: Kamailio
                    host: sip.example.net
                    port: 5060
                    transport: udp
                    mode: managed
                    contact_strategy: masquerade
                    max_expires: 3600
                    invite_source_cidrs:
                      - 198.51.100.0/24
                    strict_path: true
                    keepalive_seconds: 30
                    managed_registration: ''
                    user_source: kamailio
                    kamailio:
                      driver: mysql
                      host: db.example.net
                      port: 3306
                      user: pgw_reader
                      database: kamailio
                      tls: verify
                      password_set: true
                      use_domain: true
                      subscriber_table: subscriber
                      username_column: username
                      domain_column: domain
                      password_column: password
                      ha1_column: ha1
                      domain_table: domain
                      domain_table_column: domain
                    app_auth: digest
                    created_at: '2026-11-02T08:32:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: Another upstream, of any tenant, has the host or one of the domains.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: 'host: pbx.example.com is already served by another upstream'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    CreateUpstreamRequest:
      type: object
      additionalProperties: false
      required:
        - name
        - host
      properties:
        name:
          type: string
          minLength: 1
        host:
          type: string
          description: >-
            The PBX's DNS name or IP address, without a port or an IPv6 zone.
            pgw sends to this address, and apps can register to it as their SIP
            domain.
        domains:
          type: array
          items:
            type: string
            examples:
              - acme.example.com
              - '*.example.com'
          description: |
            The SIP domains, besides `host`, that apps register to through
            this upstream: DNS names, and `*.` and a DNS name, which matches
            any name under it at any depth but not the name itself. An
            upstream whose users come from Kamailio takes none. On a managed
            upstream, each user names its domain. pgw stores them in lower
            case, sorted, and returns `400` for an entry that isn't a DNS
            name or a wildcard, for a wildcard on a single label or an ICANN
            public suffix, such as `*.lan` or `*.com`, for an entry listed
            twice, and for the upstream's own host.
        port:
          type: integer
          minimum: 1
          maximum: 65535
          default: 5060
        transport:
          type: string
          enum:
            - udp
            - tcp
          default: udp
          description: pgw doesn't connect to PBXs over TLS.
        max_expires:
          type: integer
          minimum: 1
          maximum: 4294967295
          default: 3600
          description: The registration expiry, in seconds, that pgw asks the PBX for.
        invite_source_cidrs:
          type: array
          items:
            type: string
            examples:
              - 203.0.113.10/32
          description: |
            The CIDR prefixes that may send calls to pgw for this upstream.
            Required when `host` is a DNS name. When empty, pgw accepts calls
            from the IP address in `host`. pgw stores each prefix with its host
            bits cleared, so `10.0.0.1/8` becomes `10.0.0.0/8`.
        strict_path:
          type: boolean
          default: true
          description: |
            Refuse a registration when the PBX's answer doesn't keep pgw's
            Path. The PBX then never sends calls past pgw.
        mode:
          type: string
          enum:
            - passthrough
            - managed
          default: passthrough
          description: >
            `passthrough`: the PBX checks each app's password. `managed`: pgw
            checks

            it against the upstream's users and registers at the PBX itself,

            with `contact_strategy` `masquerade`. It can't change later.
        keepalive_seconds:
          type: integer
          default: 30
          description: |
            Send the PBX an OPTIONS at this interval, in seconds, and report
            whether it answers in the `pgw_upstream_up` metric. The OPTIONS
            also keeps a NAT or firewall on the path from forgetting the PBX's
            connection. `0` sends none; otherwise from 5 to 3600.
          oneOf:
            - const: 0
            - minimum: 5
              maximum: 3600
        realm:
          type: string
          description: >
            Managed mode only; a passthrough upstream with a realm gets 400. The

            digest realm that pgw challenges apps with, at most 128 bytes. The

            default is `host`, or on a Kamailio upstream with `use_domain`, the

            domain that the app registers to. Set it when apps were set up with
            the PBX's

            own realm, such as Asterisk's default `asterisk`. No quotes,

            backslashes, or control characters. It can't change later.
        managed_registration:
          type: string
          enum:
            - ''
            - per_user
            - per_device
          description: >
            Managed mode only; a passthrough upstream with a value gets 400. How
            pgw

            registers the upstream's devices at the PBX. `per_user` registers
            one

            contact per user and pgw rings every device of the user itself, so
            the

            PBX needs a free contact per user rather than one per device.

            `per_device` registers each device, so the PBX sees and limits
            devices.

            Omit to use the gateway default.
        contact_strategy:
          type: string
          enum:
            - path
            - masquerade
          description: >
            The default is `path`, or `masquerade` in managed mode, which

            allows no other value. How the PBX reaches the app through pgw. With
            `path`, the PBX gets

            the app's Contact and a Path to pgw. With `masquerade`, the PBX

            gets pgw's own address as the Contact, for a PBX without Path

            support, and `strict_path` has no effect. It can't change later.
        user_source:
          type: string
          enum:
            - pgw
            - kamailio
          default: pgw
          description: |
            Managed mode only. Where pgw reads the upstream's users: `pgw`,
            from the users that you add through this API, or `kamailio`,
            from a Kamailio database, which `kamailio` describes. It can't
            change later.
        kamailio:
          $ref: '#/components/schemas/KamailioRequest'
        app_auth:
          type: string
          enum:
            - digest
            - bearer
            - both
          default: digest
          description: |
            Managed mode only for `bearer` and `both`. How apps authenticate
            their REGISTER to pgw: `digest`, with the user's password,
            `bearer`, with an access token from the issuer that `bearer`
            describes, or `both`, either one.
        bearer:
          $ref: '#/components/schemas/BearerRequest'
    Upstream:
      type: object
      required:
        - id
        - name
        - host
        - port
        - transport
        - mode
        - contact_strategy
        - max_expires
        - invite_source_cidrs
        - strict_path
        - keepalive_seconds
        - managed_registration
        - user_source
        - app_auth
        - created_at
      properties:
        id:
          type: string
        name:
          type: string
        host:
          type: string
        domains:
          type: array
          items:
            type: string
          description: The upstream's domains, sorted. Absent when it has none.
        port:
          type: integer
        transport:
          type: string
          enum:
            - udp
            - tcp
            - tls
          description: |
            pgw doesn't connect to PBXs over `tls`, so registrations to such an
            upstream fail. Change it to `udp` or `tcp`; until then, any other
            change gets 400.
        mode:
          type: string
          enum:
            - passthrough
            - managed
        contact_strategy:
          type: string
          enum:
            - path
            - masquerade
        max_expires:
          type: integer
        invite_source_cidrs:
          type: array
          items:
            type: string
        strict_path:
          type: boolean
        keepalive_seconds:
          type: integer
        realm:
          type: string
          description: The digest realm of a managed upstream. Absent when it is the host.
        managed_registration:
          type: string
          enum:
            - ''
            - per_user
            - per_device
          description: Empty when the upstream uses the gateway default.
        user_source:
          type: string
          enum:
            - pgw
            - kamailio
        kamailio:
          $ref: '#/components/schemas/Kamailio'
        app_auth:
          type: string
          enum:
            - digest
            - bearer
            - both
        bearer:
          $ref: '#/components/schemas/Bearer'
        created_at:
          type: string
          format: date-time
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: What went wrong. Never contains the values that you sent.
    KamailioRequest:
      type: object
      additionalProperties: false
      description: |
        The Kamailio database of an upstream with `user_source` `kamailio`.
        pgw connects to it over TCP and reads its tables before it stores
        the upstream, and answers 400 with the step that failed. On create,
        `driver`, `host`, `user`, `password`, and `database` are required,
        and a table or column left out gets Kamailio's own name. On update,
        each field replaces the stored one. A table or column name is a
        letter or an underscore, then at most 63 letters, digits, or
        underscores.
      properties:
        driver:
          type: string
          enum:
            - mysql
            - postgres
          description: '`mysql` also reads MariaDB.'
        host:
          type: string
          description: The database's DNS name or IP address, without a port.
        port:
          type: integer
          minimum: 1
          maximum: 65535
          description: The default is 3306 for `mysql` and 5432 for `postgres`.
        user:
          type: string
          minLength: 1
          maxLength: 128
          description: >-
            The database user, which needs only `SELECT` on the subscriber and
            domain tables.
        password:
          type: string
          minLength: 1
          maxLength: 256
          writeOnly: true
          description: The database user's password. pgw encrypts it and never returns it.
        database:
          type: string
          minLength: 1
          maxLength: 64
        tls:
          type: string
          enum:
            - 'off'
            - require
            - verify
          default: verify
          description: |
            `verify`: TLS, with the server's certificate checked against the
            system's roots and `host`. `require`: TLS without that check, for
            a server with a self-signed certificate. `off`: plain TCP.
        use_domain:
          type: boolean
          default: true
          description: |
            Look subscribers up by username and domain, as Kamailio's
            `use_domain` does, and accept registrations to the domains in the
            domain table. When false, pgw looks subscribers up by username
            and doesn't read the domain table. It can't change later.
        subscriber_table:
          type: string
          default: subscriber
        username_column:
          type: string
          default: username
        domain_column:
          type: string
          default: domain
        password_column:
          type: string
          default: password
          description: >-
            Empty when the table keeps no plain passwords. It can't be empty
            when `ha1_column` is.
        ha1_column:
          type: string
          default: ha1
          description: >-
            Empty when the table keeps no `ha1` hashes. It can't be empty when
            `password_column` is.
        domain_table:
          type: string
          default: domain
        domain_table_column:
          type: string
          default: domain
    BearerRequest:
      type: object
      additionalProperties: false
      description: |
        The issuer of the access tokens that apps present, required with
        `app_auth` `bearer` or `both` and refused with `digest`. On create,
        every field is required. On update, each field present replaces the
        stored one.
      properties:
        issuer:
          type: string
          maxLength: 1024
          description: Compared byte for byte with the token's `iss` claim.
        audience:
          type: string
          maxLength: 1024
          description: Must be in the token's `aud` claim.
        jwks_url:
          type: string
          maxLength: 1024
          description: |
            The issuer's JSON Web Key Set. An `https` URL with a host and
            without user information. pgw fetches it when a token names a
            key that pgw doesn't have, at most once a minute, and every hour.
    Kamailio:
      type: object
      required:
        - driver
        - host
        - port
        - user
        - database
        - tls
        - password_set
        - use_domain
        - subscriber_table
        - username_column
        - domain_column
        - password_column
        - ha1_column
        - domain_table
        - domain_table_column
      properties:
        driver:
          type: string
          enum:
            - mysql
            - postgres
        host:
          type: string
        port:
          type: integer
        user:
          type: string
        database:
          type: string
        tls:
          type: string
          enum:
            - 'off'
            - require
            - verify
        password_set:
          type: boolean
          description: Whether pgw holds the database password. pgw never returns it.
        use_domain:
          type: boolean
        subscriber_table:
          type: string
        username_column:
          type: string
        domain_column:
          type: string
        password_column:
          type: string
        ha1_column:
          type: string
        domain_table:
          type: string
        domain_table_column:
          type: string
    Bearer:
      type: object
      required:
        - issuer
        - audience
        - jwks_url
      properties:
        issuer:
          type: string
        audience:
          type: string
        jwks_url:
          type: string
  responses:
    BadRequest:
      description: >-
        The request body or a parameter isn't valid. The message names the
        field.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            field:
              summary: A field that isn't valid
              value:
                error: 'invalid request: platform must be "ios", "android", or "web"'
            json:
              summary: A body that isn't valid JSON
              value:
                error: 'invalid JSON body: unknown field "colour"'
            limit:
              summary: A query parameter out of range
              value:
                error: limit must be from 1 to 1000
    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.