Skip to main content
POST

Authorizations

Authorization
string
header
required

The tenant API key that POST /bootstrap returned.

Body

application/json
name
string
required
Minimum string length: 1
host
string
required

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
string[]

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
integer
default:5060
Required range: 1 <= x <= 65535
transport
enum<string>
default:udp

pgw doesn't connect to PBXs over TLS.

Available options:
udp,
tcp
max_expires
integer
default:3600

The registration expiry, in seconds, that pgw asks the PBX for.

Required range: 1 <= x <= 4294967295
invite_source_cidrs
string[]

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
boolean
default:true

Refuse a registration when the PBX's answer doesn't keep pgw's Path. The PBX then never sends calls past pgw.

mode
enum<string>
default:passthrough

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.

Available options:
passthrough,
managed
keepalive_seconds
default:30

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.

realm
string

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
enum<string>

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.

Available options:
,
per_user,
per_device
contact_strategy
enum<string>

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.

Available options:
path,
masquerade
user_source
enum<string>
default:pgw

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.

Available options:
pgw,
kamailio
kamailio
object

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.

app_auth
enum<string>
default:digest

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.

Available options:
digest,
bearer,
both
bearer
object

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.

Response

The upstream was created.

id
string
required
name
string
required
host
string
required
port
integer
required
transport
enum<string>
required

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.

Available options:
udp,
tcp,
tls
mode
enum<string>
required
Available options:
passthrough,
managed
contact_strategy
enum<string>
required
Available options:
path,
masquerade
max_expires
integer
required
invite_source_cidrs
string[]
required
strict_path
boolean
required
keepalive_seconds
integer
required
managed_registration
enum<string>
required

Empty when the upstream uses the gateway default.

Available options:
,
per_user,
per_device
user_source
enum<string>
required
Available options:
pgw,
kamailio
app_auth
enum<string>
required
Available options:
digest,
bearer,
both
created_at
string<date-time>
required
domains
string[]

The upstream's domains, sorted. Absent when it has none.

realm
string

The digest realm of a managed upstream. Absent when it is the host.

kamailio
object
bearer
object