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.
POST
/
upstreams
A valid request URL is required to generate request examples
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_strategymasquerade. It can't change later.
Available options:
passthrough,
managed
keepalive_seconds
Option 1 · integerOption 2 · integer
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_sourcekamailio.
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.
Show child attributes
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_authbearer or both and refused with digest. On create,
every field is required. On update, each field present replaces the
stored one.
Show child attributes
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
Show child attributes
bearer
object
Show child attributes
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"pgw","description":"Documentation for pgw, the RFC 8599 push gateway for SIP.","colors":{"primary":"#2563eb","light":"#38bdf8","dark":"#0369a1"},"logo":{"light":"https://mintcdn.com/pgw/AxRzHBtQGOZ6Qv0v/logo/light.svg?fit=max\u0026auto=format\u0026n=AxRzHBtQGOZ6Qv0v\u0026q=85\u0026s=3247acd1cff3a49682e5cb75ed65f662","dark":"https://mintcdn.com/pgw/AxRzHBtQGOZ6Qv0v/logo/dark.svg?fit=max\u0026auto=format\u0026n=AxRzHBtQGOZ6Qv0v\u0026q=85\u0026s=a79e42db455abadbc9e15d88c72bac43","href":"https://pgw.sipmicro.services/"},"favicon":"https://mintcdn.com/pgw/AxRzHBtQGOZ6Qv0v/favicon.svg?fit=max\u0026auto=format\u0026n=AxRzHBtQGOZ6Qv0v\u0026q=85\u0026s=4a2f2dbd7c24e23be16239974fed9f48","api":{"playground":{"display":"interactive","proxy":false},"examples":{"languages":["curl","go","python","javascript"]}},"appearance":{"default":"dark"},"background":{"color":{"dark":"#000000"}},"navbar":{"primary":{"type":"button","label":"Download","href":"https://pgw.sipmicro.services/#download"}},"fonts":{"family":"Inter"},"contextual":{"options":["copy","view","chatgpt","claude"],"display":"header"},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"pgw","hasAudioNarration":false,"actualSubdomain":"pgw","customDomains":["docs.pgw.sipmicro.services"],"gitSource":{"type":"github","owner":"civilcoder55","repo":"pgw-docs","deployBranch":"main","contentDirectory":"","isPrivate":true,"mountPath":"","label":"","_id":"6af9754d4fd4397144e5b6cb"},"entitlements":{"AI_CHAT":{"status":"ENABLED"},"WEB_MCP":{"status":"ENABLED"},"NARRATION":{"status":"ENABLED"}},"buildId":"6afd77f05780c727fdcc104e","clientVersion":"0.0.4177","searchFilterCounts":[{"language":"default","tag":"API reference","count":28},{"language":"default","tag":"Endpoints","count":24},{"language":"default","tag":"Operations","count":11},{"language":"default","tag":"Configuration","count":11},{"language":"default","tag":"Get started","count":8},{"language":"default","tag":"Upstreams","count":8},{"language":"default","tag":"App developers","count":7},{"language":"default","tag":"Platform","count":7},{"language":"default","tag":"Observability","count":6},{"language":"default","tag":"Reference","count":6}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":true,"hasWebMcpPermissions":true,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"starter-pricing","enabled":true,"variant":{"name":"control","enabled":true,"payload":{"type":"string","value":"control"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"wildcard-email-auth","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[{"filePath":"style.css","content":":root{--sidebar-width: 14rem}"}],"page":{"pagePath":"api-reference/upstreams/add-a-pbx","slug":"/api-reference/upstreams/add-a-pbx","pageMetadata":{"title":"Add a PBX","description":"Adds a PBX that pgw registers apps with. pgw finds the upstream for a\nREGISTER by the host of its request URI: an upstream whose `host` or\none of whose `domains` equals it, else the upstream with the longest\n`*.` wildcard in `domains` that matches it. Each host and domain\nbelongs to one upstream across the whole pgw install, and no host or\ndomain can equal, fall under, or cover a name of another tenant,\nincluding a domain in its Kamailio domain table. pgw stores\nhosts and domains in canonical form: a DNS name in lower case, or an\nIP address without brackets.\n\npgw returns `400` when `transport` isn't `udp` or `tcp`, when\n`host` is a DNS name and `invite_source_cidrs` is empty, and when\nan upstream whose users come from Kamailio has `domains`.\n","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml post /upstreams","href":"/api-reference/upstreams/add-a-pbx","autogeneratedByOpenApi":true},"description":{"compiledSource":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Adds a PBX that pgw registers apps with. pgw finds the upstream for a\\nREGISTER by the host of its request URI: an upstream whose \", _jsx(_components.code, {\n children: \"host\"\n }), \" or\\none of whose \", _jsx(_components.code, {\n children: \"domains\"\n }), \" equals it, else the upstream with the longest\\n\", _jsx(_components.code, {\n children: \"*.\"\n }), \" wildcard in \", _jsx(_components.code, {\n children: \"domains\"\n }), \" that matches it. Each host and domain\\nbelongs to one upstream across the whole pgw install, and no host or\\ndomain can equal, fall under, or cover a name of another tenant,\\nincluding a domain in its Kamailio domain table. pgw stores\\nhosts and domains in canonical form: a DNS name in lower case, or an\\nIP address without brackets.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"pgw returns \", _jsx(_components.code, {\n children: \"400\"\n }), \" when \", _jsx(_components.code, {\n children: \"transport\"\n }), \" isn’t \", _jsx(_components.code, {\n children: \"udp\"\n }), \" or \", _jsx(_components.code, {\n children: \"tcp\"\n }), \", when\\n\", _jsx(_components.code, {\n children: \"host\"\n }), \" is a DNS name and \", _jsx(_components.code, {\n children: \"invite_source_cidrs\"\n }), \" is empty, and when\\nan upstream whose users come from Kamailio has \", _jsx(_components.code, {\n children: \"domains\"\n }), \".\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){return _jsx(_Fragment,{})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Add a PBX","description":"Adds a PBX that pgw registers apps with. pgw finds the upstream for a\nREGISTER by the host of its request URI: an upstream whose `host` or\none of whose `domains` equals it, else the upstream with the longest\n`*.` wildcard in `domains` that matches it. Each host and domain\nbelongs to one upstream across the whole pgw install, and no host or\ndomain can equal, fall under, or cover a name of another tenant,\nincluding a domain in its Kamailio domain table. pgw stores\nhosts and domains in canonical form: a DNS name in lower case, or an\nIP address without brackets.\n\npgw returns `400` when `transport` isn't `udp` or `tcp`, when\n`host` is a DNS name and `invite_source_cidrs` is empty, and when\nan upstream whose users come from Kamailio has `domains`.\n","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml post /upstreams","href":"/api-reference/upstreams/add-a-pbx","autogeneratedByOpenApi":true}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"tags":["Upstreams"],"operationId":"createUpstream","summary":"Add a PBX","description":"Adds a PBX that pgw registers apps with. pgw finds the upstream for a\nREGISTER by the host of its request URI: an upstream whose `host` or\none of whose `domains` equals it, else the upstream with the longest\n`*.` wildcard in `domains` that matches it. Each host and domain\nbelongs to one upstream across the whole pgw install, and no host or\ndomain can equal, fall under, or cover a name of another tenant,\nincluding a domain in its Kamailio domain table. pgw stores\nhosts and domains in canonical form: a DNS name in lower case, or an\nIP address without brackets.\n\npgw returns `400` when `transport` isn't `udp` or `tcp`, when\n`host` is a DNS name and `invite_source_cidrs` is empty, and when\nan upstream whose users come from Kamailio has `domains`.\n","requestBody":"52fe5bba-bced-45ad-91e4-843167422b55","responses":{"201":"38eb2ac5-a4c9-4b1e-b583-bdc2ccf1345f","400":"11d48260-47ef-4d71-b4ab-40dbdbb867ed","401":"c47bdc8a-76de-441c-b44a-d1f6b7e66e8c","409":"5f055af5-3f49-41cc-aa9d-9a4e7db0b25d","500":"1e2a650e-8a5b-49b0-aada-279546814528"},"method":"post","type":"path","servers":["962d9e3c-eaaf-4447-9e2e-c710d720d8c4","ca7875ea-5910-467e-ba3d-4340b8927ded"],"security":["d5d8905a-dbea-4877-8c19-6dd7a6f5eb2e"],"path":"/upstreams","baseUrlOptions":["{baseUrl}","http://localhost:8080/api/v1"],"title":"Add a PBX","codeSamples":[],"requestExampleLanguages":["bash","go","python","javascript"],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated","disableProxy":true},"dependencies":{"parameters":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["name","host"],"properties":{"name":{"type":"string","minLength":1,"isRequired":true,"uniqueKey":"name","typeLabel":"string"},"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.","isRequired":true,"uniqueKey":"host","typeLabel":"string"},"domains":{"type":"array","items":{"type":"string","examples":["acme.example.com","*.example.com"],"uniqueKey":"domains.items.[INDEX]","typeLabel":"string"},"description":"The SIP domains, besides `host`, that apps register to through\nthis upstream: DNS names, and `*.` and a DNS name, which matches\nany name under it at any depth but not the name itself. An\nupstream whose users come from Kamailio takes none. On a managed\nupstream, each user names its domain. pgw stores them in lower\ncase, sorted, and returns `400` for an entry that isn't a DNS\nname or a wildcard, for a wildcard on a single label or an ICANN\npublic suffix, such as `*.lan` or `*.com`, for an entry listed\ntwice, and for the upstream's own host.\n","uniqueKey":"domains","typeLabel":"string[]"},"port":{"type":"integer","minimum":1,"maximum":65535,"default":5060,"uniqueKey":"port","typeLabel":"integer"},"transport":{"type":"string","enum":["udp","tcp"],"default":"udp","description":"pgw doesn't connect to PBXs over TLS.","uniqueKey":"transport","typeLabel":"enum\u003cstring>"},"max_expires":{"type":"integer","minimum":1,"maximum":4294967295,"default":3600,"description":"The registration expiry, in seconds, that pgw asks the PBX for.","uniqueKey":"max_expires","typeLabel":"integer"},"invite_source_cidrs":{"type":"array","items":{"type":"string","examples":["203.0.113.10/32"],"uniqueKey":"invite_source_cidrs.items.[INDEX]","typeLabel":"string"},"description":"The CIDR prefixes that may send calls to pgw for this upstream.\nRequired when `host` is a DNS name. When empty, pgw accepts calls\nfrom the IP address in `host`. pgw stores each prefix with its host\nbits cleared, so `10.0.0.1/8` becomes `10.0.0.0/8`.\n","uniqueKey":"invite_source_cidrs","typeLabel":"string[]"},"strict_path":{"type":"boolean","default":true,"description":"Refuse a registration when the PBX's answer doesn't keep pgw's\nPath. The PBX then never sends calls past pgw.\n","uniqueKey":"strict_path","typeLabel":"boolean"},"mode":{"type":"string","enum":["passthrough","managed"],"default":"passthrough","description":"`passthrough`: the PBX checks each app's password. `managed`: pgw checks\nit against the upstream's users and registers at the PBX itself,\nwith `contact_strategy` `masquerade`. It can't change later.\n","uniqueKey":"mode","typeLabel":"enum\u003cstring>"},"keepalive_seconds":{"oneOf":[{"type":"integer","description":"Send the PBX an OPTIONS at this interval, in seconds, and report\nwhether it answers in the `pgw_upstream_up` metric. The OPTIONS\nalso keeps a NAT or firewall on the path from forgetting the PBX's\nconnection. `0` sends none; otherwise from 5 to 3600.\n","default":30,"const":0,"uniqueKey":"keepalive_seconds.oneOf.0","typeLabel":"integer"},{"type":"integer","description":"Send the PBX an OPTIONS at this interval, in seconds, and report\nwhether it answers in the `pgw_upstream_up` metric. The OPTIONS\nalso keeps a NAT or firewall on the path from forgetting the PBX's\nconnection. `0` sends none; otherwise from 5 to 3600.\n","default":30,"maximum":3600,"minimum":5,"uniqueKey":"keepalive_seconds.oneOf.1","typeLabel":"integer"}],"uniqueKey":"keepalive_seconds","typeLabel":"integer"},"realm":{"type":"string","description":"Managed mode only; a passthrough upstream with a realm gets 400. The\ndigest realm that pgw challenges apps with, at most 128 bytes. The\ndefault is `host`, or on a Kamailio upstream with `use_domain`, the\ndomain that the app registers to. Set it when apps were set up with the PBX's\nown realm, such as Asterisk's default `asterisk`. No quotes,\nbackslashes, or control characters. It can't change later.\n","uniqueKey":"realm","typeLabel":"string"},"managed_registration":{"type":"string","enum":["","per_user","per_device"],"description":"Managed mode only; a passthrough upstream with a value gets 400. How pgw\nregisters the upstream's devices at the PBX. `per_user` registers one\ncontact per user and pgw rings every device of the user itself, so the\nPBX needs a free contact per user rather than one per device.\n`per_device` registers each device, so the PBX sees and limits devices.\nOmit to use the gateway default.\n","uniqueKey":"managed_registration","typeLabel":"enum\u003cstring>"},"contact_strategy":{"type":"string","enum":["path","masquerade"],"description":"The default is `path`, or `masquerade` in managed mode, which\nallows no other value. How the PBX reaches the app through pgw. With `path`, the PBX gets\nthe app's Contact and a Path to pgw. With `masquerade`, the PBX\ngets pgw's own address as the Contact, for a PBX without Path\nsupport, and `strict_path` has no effect. It can't change later.\n","uniqueKey":"contact_strategy","typeLabel":"enum\u003cstring>"},"user_source":{"type":"string","enum":["pgw","kamailio"],"default":"pgw","description":"Managed mode only. Where pgw reads the upstream's users: `pgw`,\nfrom the users that you add through this API, or `kamailio`,\nfrom a Kamailio database, which `kamailio` describes. It can't\nchange later.\n","uniqueKey":"user_source","typeLabel":"enum\u003cstring>"},"kamailio":{"type":"object","additionalProperties":false,"description":"The Kamailio database of an upstream with `user_source` `kamailio`.\npgw connects to it over TCP and reads its tables before it stores\nthe upstream, and answers 400 with the step that failed. On create,\n`driver`, `host`, `user`, `password`, and `database` are required,\nand a table or column left out gets Kamailio's own name. On update,\neach field replaces the stored one. A table or column name is a\nletter or an underscore, then at most 63 letters, digits, or\nunderscores.\n","properties":{"driver":{"type":"string","enum":["mysql","postgres"],"description":"`mysql` also reads MariaDB.","uniqueKey":"kamailio.driver","typeLabel":"enum\u003cstring>"},"host":{"type":"string","description":"The database's DNS name or IP address, without a port.","uniqueKey":"kamailio.host","typeLabel":"string"},"port":{"type":"integer","minimum":1,"maximum":65535,"description":"The default is 3306 for `mysql` and 5432 for `postgres`.","uniqueKey":"kamailio.port","typeLabel":"integer"},"user":{"type":"string","minLength":1,"maxLength":128,"description":"The database user, which needs only `SELECT` on the subscriber and domain tables.","uniqueKey":"kamailio.user","typeLabel":"string"},"password":{"type":"string","minLength":1,"maxLength":256,"writeOnly":true,"description":"The database user's password. pgw encrypts it and never returns it.","uniqueKey":"kamailio.password","typeLabel":"string"},"database":{"type":"string","minLength":1,"maxLength":64,"uniqueKey":"kamailio.database","typeLabel":"string"},"tls":{"type":"string","enum":["off","require","verify"],"default":"verify","description":"`verify`: TLS, with the server's certificate checked against the\nsystem's roots and `host`. `require`: TLS without that check, for\na server with a self-signed certificate. `off`: plain TCP.\n","uniqueKey":"kamailio.tls","typeLabel":"enum\u003cstring>"},"use_domain":{"type":"boolean","default":true,"description":"Look subscribers up by username and domain, as Kamailio's\n`use_domain` does, and accept registrations to the domains in the\ndomain table. When false, pgw looks subscribers up by username\nand doesn't read the domain table. It can't change later.\n","uniqueKey":"kamailio.use_domain","typeLabel":"boolean"},"subscriber_table":{"type":"string","default":"subscriber","uniqueKey":"kamailio.subscriber_table","typeLabel":"string"},"username_column":{"type":"string","default":"username","uniqueKey":"kamailio.username_column","typeLabel":"string"},"domain_column":{"type":"string","default":"domain","uniqueKey":"kamailio.domain_column","typeLabel":"string"},"password_column":{"type":"string","default":"password","description":"Empty when the table keeps no plain passwords. It can't be empty when `ha1_column` is.","uniqueKey":"kamailio.password_column","typeLabel":"string"},"ha1_column":{"type":"string","default":"ha1","description":"Empty when the table keeps no `ha1` hashes. It can't be empty when `password_column` is.","uniqueKey":"kamailio.ha1_column","typeLabel":"string"},"domain_table":{"type":"string","default":"domain","uniqueKey":"kamailio.domain_table","typeLabel":"string"},"domain_table_column":{"type":"string","default":"domain","uniqueKey":"kamailio.domain_table_column","typeLabel":"string"}},"uniqueKey":"kamailio","typeLabel":"object"},"app_auth":{"type":"string","enum":["digest","bearer","both"],"default":"digest","description":"Managed mode only for `bearer` and `both`. How apps authenticate\ntheir REGISTER to pgw: `digest`, with the user's password,\n`bearer`, with an access token from the issuer that `bearer`\ndescribes, or `both`, either one.\n","uniqueKey":"app_auth","typeLabel":"enum\u003cstring>"},"bearer":{"type":"object","additionalProperties":false,"description":"The issuer of the access tokens that apps present, required with\n`app_auth` `bearer` or `both` and refused with `digest`. On create,\nevery field is required. On update, each field present replaces the\nstored one.\n","properties":{"issuer":{"type":"string","maxLength":1024,"description":"Compared byte for byte with the token's `iss` claim.","uniqueKey":"bearer.issuer","typeLabel":"string"},"audience":{"type":"string","maxLength":1024,"description":"Must be in the token's `aud` claim.","uniqueKey":"bearer.audience","typeLabel":"string"},"jwks_url":{"type":"string","maxLength":1024,"description":"The issuer's JSON Web Key Set. An `https` URL with a host and\nwithout user information. pgw fetches it when a token names a\nkey that pgw doesn't have, at most once a minute, and every hour.\n","uniqueKey":"bearer.jwks_url","typeLabel":"string"}},"uniqueKey":"bearer","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"passthrough":{"title":"passthrough","summary":"Passthrough PBX","value":{"name":"asterisk","host":"pbx.example.com","domains":["*.example.com"],"invite_source_cidrs":["203.0.113.10/32"]}},"managed":{"title":"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":{"title":"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"}}}},"exampleType":"examples"}},"exampleType":"examples"},"responses":{"38eb2ac5-a4c9-4b1e-b583-bdc2ccf1345f":{"description":"The upstream was created.","content":{"application/json":{"schema":{"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","isRequired":true,"uniqueKey":"id","typeLabel":"string"},"name":{"type":"string","isRequired":true,"uniqueKey":"name","typeLabel":"string"},"host":{"type":"string","isRequired":true,"uniqueKey":"host","typeLabel":"string"},"port":{"type":"integer","isRequired":true,"uniqueKey":"port","typeLabel":"integer"},"transport":{"type":"string","enum":["udp","tcp","tls"],"description":"pgw doesn't connect to PBXs over `tls`, so registrations to such an\nupstream fail. Change it to `udp` or `tcp`; until then, any other\nchange gets 400.\n","isRequired":true,"uniqueKey":"transport","typeLabel":"enum\u003cstring>"},"mode":{"type":"string","enum":["passthrough","managed"],"isRequired":true,"uniqueKey":"mode","typeLabel":"enum\u003cstring>"},"contact_strategy":{"type":"string","enum":["path","masquerade"],"isRequired":true,"uniqueKey":"contact_strategy","typeLabel":"enum\u003cstring>"},"max_expires":{"type":"integer","isRequired":true,"uniqueKey":"max_expires","typeLabel":"integer"},"invite_source_cidrs":{"type":"array","items":{"type":"string","uniqueKey":"invite_source_cidrs.items.[INDEX]","typeLabel":"string"},"isRequired":true,"uniqueKey":"invite_source_cidrs","typeLabel":"string[]"},"strict_path":{"type":"boolean","isRequired":true,"uniqueKey":"strict_path","typeLabel":"boolean"},"keepalive_seconds":{"type":"integer","isRequired":true,"uniqueKey":"keepalive_seconds","typeLabel":"integer"},"managed_registration":{"type":"string","enum":["","per_user","per_device"],"description":"Empty when the upstream uses the gateway default.","isRequired":true,"uniqueKey":"managed_registration","typeLabel":"enum\u003cstring>"},"user_source":{"type":"string","enum":["pgw","kamailio"],"isRequired":true,"uniqueKey":"user_source","typeLabel":"enum\u003cstring>"},"app_auth":{"type":"string","enum":["digest","bearer","both"],"isRequired":true,"uniqueKey":"app_auth","typeLabel":"enum\u003cstring>"},"created_at":{"type":"string","format":"date-time","isRequired":true,"uniqueKey":"created_at","typeLabel":"string\u003cdate-time>"},"domains":{"type":"array","items":{"type":"string","uniqueKey":"domains.items.[INDEX]","typeLabel":"string"},"description":"The upstream's domains, sorted. Absent when it has none.","uniqueKey":"domains","typeLabel":"string[]"},"realm":{"type":"string","description":"The digest realm of a managed upstream. Absent when it is the host.","uniqueKey":"realm","typeLabel":"string"},"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"],"isRequired":true,"uniqueKey":"kamailio.driver","typeLabel":"enum\u003cstring>"},"host":{"type":"string","isRequired":true,"uniqueKey":"kamailio.host","typeLabel":"string"},"port":{"type":"integer","isRequired":true,"uniqueKey":"kamailio.port","typeLabel":"integer"},"user":{"type":"string","isRequired":true,"uniqueKey":"kamailio.user","typeLabel":"string"},"database":{"type":"string","isRequired":true,"uniqueKey":"kamailio.database","typeLabel":"string"},"tls":{"type":"string","enum":["off","require","verify"],"isRequired":true,"uniqueKey":"kamailio.tls","typeLabel":"enum\u003cstring>"},"password_set":{"type":"boolean","description":"Whether pgw holds the database password. pgw never returns it.","isRequired":true,"uniqueKey":"kamailio.password_set","typeLabel":"boolean"},"use_domain":{"type":"boolean","isRequired":true,"uniqueKey":"kamailio.use_domain","typeLabel":"boolean"},"subscriber_table":{"type":"string","isRequired":true,"uniqueKey":"kamailio.subscriber_table","typeLabel":"string"},"username_column":{"type":"string","isRequired":true,"uniqueKey":"kamailio.username_column","typeLabel":"string"},"domain_column":{"type":"string","isRequired":true,"uniqueKey":"kamailio.domain_column","typeLabel":"string"},"password_column":{"type":"string","isRequired":true,"uniqueKey":"kamailio.password_column","typeLabel":"string"},"ha1_column":{"type":"string","isRequired":true,"uniqueKey":"kamailio.ha1_column","typeLabel":"string"},"domain_table":{"type":"string","isRequired":true,"uniqueKey":"kamailio.domain_table","typeLabel":"string"},"domain_table_column":{"type":"string","isRequired":true,"uniqueKey":"kamailio.domain_table_column","typeLabel":"string"}},"uniqueKey":"kamailio","typeLabel":"object"},"bearer":{"type":"object","required":["issuer","audience","jwks_url"],"properties":{"issuer":{"type":"string","isRequired":true,"uniqueKey":"bearer.issuer","typeLabel":"string"},"audience":{"type":"string","isRequired":true,"uniqueKey":"bearer.audience","typeLabel":"string"},"jwks_url":{"type":"string","isRequired":true,"uniqueKey":"bearer.jwks_url","typeLabel":"string"}},"uniqueKey":"bearer","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"passthrough":{"title":"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":{"title":"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":{"title":"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"}}},"exampleType":"examples"}},"exampleType":"examples"},"11d48260-47ef-4d71-b4ab-40dbdbb867ed":{"description":"The request body or a parameter isn't valid. The message names the field.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"What went wrong. Never contains the values that you sent.","isRequired":true,"uniqueKey":"error","typeLabel":"string"}},"uniqueKey":"","typeLabel":"object"},"examples":{"field":{"title":"field","summary":"A field that isn't valid","value":{"error":"invalid request: platform must be \"ios\", \"android\", or \"web\""}},"json":{"title":"json","summary":"A body that isn't valid JSON","value":{"error":"invalid JSON body: unknown field \"colour\""}},"limit":{"title":"limit","summary":"A query parameter out of range","value":{"error":"limit must be from 1 to 1000"}}},"exampleType":"examples"}},"exampleType":"examples"},"c47bdc8a-76de-441c-b44a-d1f6b7e66e8c":{"description":"The API key is missing or unknown.","headers":{"WWW-Authenticate":{"schema":{"type":"string","const":"Bearer"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"What went wrong. Never contains the values that you sent.","isRequired":true,"uniqueKey":"error","typeLabel":"string"}},"uniqueKey":"","typeLabel":"object"},"example":{"error":"missing or unknown API key"},"examples":{"Example":{"title":"Example","value":{"error":"missing or unknown API key"}}},"exampleType":"examples"}},"exampleType":"examples"},"5f055af5-3f49-41cc-aa9d-9a4e7db0b25d":{"description":"Another upstream, of any tenant, has the host or one of the domains.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"What went wrong. Never contains the values that you sent.","isRequired":true,"uniqueKey":"error","typeLabel":"string"}},"uniqueKey":"","typeLabel":"object"},"example":{"error":"host: pbx.example.com is already served by another upstream"},"examples":{"Example":{"title":"Example","value":{"error":"host: pbx.example.com is already served by another upstream"}}},"exampleType":"examples"}},"exampleType":"examples"},"1e2a650e-8a5b-49b0-aada-279546814528":{"description":"pgw failed to complete the request. The details are in pgw's log.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"What went wrong. Never contains the values that you sent.","isRequired":true,"uniqueKey":"error","typeLabel":"string"}},"uniqueKey":"","typeLabel":"object"},"example":{"error":"internal error"},"examples":{"Example":{"title":"Example","value":{"error":"internal error"}}},"exampleType":"examples"}},"exampleType":"examples"}},"security":{"d5d8905a-dbea-4877-8c19-6dd7a6f5eb2e":{"apiKey":{"type":"http","scheme":"bearer","description":"The tenant API key that `POST /bootstrap` returned.","scopes":[],"schemeName":"apiKey"}}},"servers":{"962d9e3c-eaaf-4447-9e2e-c710d720d8c4":{"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."}}},"ca7875ea-5910-467e-ba3d-4340b8927ded":{"url":"http://localhost:8080/api/v1","description":"pgw on this computer"}},"processedSecurityOptions":[{"schemes":[{"scheme":{"type":"http","scheme":"bearer","description":"The tenant API key that `POST /bootstrap` returned.","scopes":[],"schemeName":"apiKey"},"schema":{"title":"Bearer Auth","type":"string","isRequired":true,"description":"The tenant API key that `POST /bootstrap` returned.","format":"bearer","typeLabel":"string\u003cbearer>","deprecated":false},"schemeName":"apiKey","name":"Authorization"}],"title":"apiKey"}]},"originalFileLocation":"reference/openapi.yaml"},"subdomain":"pgw","siteName":"pgw","title":"Add a PBX - pgw","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-11-18T09:44:01.859Z","originalFileLocation":"api-reference/upstreams/add-a-pbx.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"dark\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"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\u0026#x27;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.\">\u003cmeta data-mint-head name=\"application-name\" content=\"pgw\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/pgw/EnF0PB9t_jslDyUs/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/pgw/EnF0PB9t_jslDyUs/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/pgw/EnF0PB9t_jslDyUs/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/pgw/EnF0PB9t_jslDyUs/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/pgw/EnF0PB9t_jslDyUs/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/pgw/EnF0PB9t_jslDyUs/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/pgw/EnF0PB9t_jslDyUs/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/pgw/EnF0PB9t_jslDyUs/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/pgw/EnF0PB9t_jslDyUs/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Add a PBX - pgw\">\u003cmeta data-mint-head property=\"og:description\" content=\"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\u0026#x27;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.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"pgw\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.pgw.sipmicro.services/api-reference/upstreams/add-a-pbx\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://pgw.mintlify.site/_mintlify/api/og/v2?division=Upstreams\u0026amp;title=Add+a+PBX\u0026amp;description=Adds+a+PBX+that+pgw+registers+apps+with.+pgw+finds+the+upstream+for+a%0AREGISTER+by+the+host+of+its+request+URI%3A+an+upstream+whose+%60host%60+or%0Aone+of+whose+%60domains\u0026amp;theme=8d7f0f3427552df5bcb33776\u0026amp;signature=044d8b4bcaef8ab5225062b5e4e3c204b983ab9d0b5908a9d7050c6086029694\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Add a PBX - pgw\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"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\u0026#x27;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.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://pgw.mintlify.site/_mintlify/api/og/v2?division=Upstreams\u0026amp;title=Add+a+PBX\u0026amp;description=Adds+a+PBX+that+pgw+registers+apps+with.+pgw+finds+the+upstream+for+a%0AREGISTER+by+the+host+of+its+request+URI%3A+an+upstream+whose+%60host%60+or%0Aone+of+whose+%60domains\u0026amp;theme=8d7f0f3427552df5bcb33776\u0026amp;signature=044d8b4bcaef8ab5225062b5e4e3c204b983ab9d0b5908a9d7050c6086029694\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/pgw/EnF0PB9t_jslDyUs/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"pgw\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#2563eb\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.pgw.sipmicro.services/api-reference/upstreams/add-a-pbx\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/upstreams/add-a-pbx.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.pgw.sipmicro.services/#organization\",\"name\":\"pgw\",\"url\":\"https://docs.pgw.sipmicro.services\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/pgw/AxRzHBtQGOZ6Qv0v/logo/light.svg?fit=max\u0026auto=format\u0026n=AxRzHBtQGOZ6Qv0v\u0026q=85\u0026s=3247acd1cff3a49682e5cb75ed65f662\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.pgw.sipmicro.services#website\",\"name\":\"pgw\",\"url\":\"https://docs.pgw.sipmicro.services\",\"publisher\":{\"@id\":\"https://docs.pgw.sipmicro.services/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.pgw.sipmicro.services/api-reference/upstreams/add-a-pbx#webpage\",\"url\":\"https://docs.pgw.sipmicro.services/api-reference/upstreams/add-a-pbx\",\"name\":\"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.\",\"dateModified\":\"2026-11-18T09:44:01.859Z\",\"isPartOf\":{\"@id\":\"https://docs.pgw.sipmicro.services#website\"},\"breadcrumb\":{\"@id\":\"https://docs.pgw.sipmicro.services/api-reference/upstreams/add-a-pbx#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.pgw.sipmicro.services/api-reference/upstreams/add-a-pbx#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Endpoints\",\"item\":\"https://docs.pgw.sipmicro.services/api-reference/tenant/create-the-first-tenant\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Upstreams\",\"item\":\"https://docs.pgw.sipmicro.services/api-reference/upstreams/list-upstreams\"},{\"@type\":\"ListItem\",\"position\":3,\"name\":\"Add a PBX\",\"item\":\"https://docs.pgw.sipmicro.services/api-reference/upstreams/add-a-pbx\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.pgw.sipmicro.services/api-reference/upstreams/add-a-pbx#apireference\",\"headline\":\"Add a PBX\",\"name\":\"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.\",\"url\":\"https://docs.pgw.sipmicro.services/api-reference/upstreams/add-a-pbx\",\"mainEntityOfPage\":{\"@id\":\"https://docs.pgw.sipmicro.services/api-reference/upstreams/add-a-pbx#webpage\"},\"dateModified\":\"2026-11-18T09:44:01.859Z\",\"publisher\":{\"@id\":\"https://docs.pgw.sipmicro.services/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.pgw.sipmicro.services#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"pgw\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"pgw\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/api-reference/upstreams/add-a-pbx.md","siteName":"pgw","nav":{"global":null,"tabs":[{"tab":"Platform","pages":[{"title":"Platform","href":""}]},{"tab":"Configuration","pages":[{"title":"Configuration","href":"/upstreams/managed-mode"}]},{"tab":"App developers","pages":[{"title":"App developers","href":"/apps/overview"}]},{"tab":"Operations","pages":[{"title":"Operations","href":"/deploy/install"}]},{"tab":"Observability","pages":[{"title":"Observability","href":"/health-checks"}]},{"tab":"API reference","groups":[{"group":"Get started","pages":[{"title":"API reference","sidebarTitle":"Introduction","icon":"book","href":"/api/introduction"},{"title":"Authenticate API requests","sidebarTitle":"Authentication","icon":"fingerprint","href":"/api/authentication"},{"title":"Handle API errors","sidebarTitle":"Errors","icon":"circle-exclamation","href":"/api/errors"},{"title":"Page through lists","sidebarTitle":"Pagination","icon":"list-ol","href":"/api/pagination"}]},{"group":"Endpoints","pages":[{"group":"Tenant","pages":[{"title":"Create the first tenant","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml post /bootstrap","href":"/api-reference/tenant/create-the-first-tenant"},{"title":"Get the caller's tenant","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml get /tenant","href":"/api-reference/tenant/get-the-callers-tenant"}]},{"group":"Apps","pages":[{"title":"List apps","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml get /apps","href":"/api-reference/apps/list-apps"},{"title":"Register an app","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml post /apps","href":"/api-reference/apps/register-an-app"},{"title":"Change an app's delivery mode or VAPID subject","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml patch /apps/{id}","href":"/api-reference/apps/change-an-apps-delivery-mode-or-vapid-subject"},{"title":"Export a web app's VAPID private key","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml get /apps/{id}/vapid-key","href":"/api-reference/apps/export-a-web-apps-vapid-private-key"}]},{"group":"Upstreams","pages":[{"title":"List upstreams","description":null,"deprecated":null,"version":null,"openapi":"/reference/openapi.yaml get /upstreams","href":"/api-reference/upstreams/list-upstreams"},{"title":"Add a PBX","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml post /upstreams","href":"/api-reference/upstreams/add-a-pbx"},{"title":"Delete an upstream","description":"Deletes an upstream that no binding uses. Bindings end when their\nregistration expires, at most `max_expires` seconds, or the PBX's\nminimum when that is longer, after the app last registered. With\n`force=true`, pgw deletes the upstream and its bindings together.\npgw can't unregister them at the PBX, so the PBX keeps them until\nthey expire, and pgw refuses the calls that it sends to them.\n","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml delete /upstreams/{id}","href":"/api-reference/upstreams/delete-an-upstream"},{"title":"Change an upstream","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml patch /upstreams/{id}","href":"/api-reference/upstreams/change-an-upstream"}]},{"group":"Users","pages":[{"title":"List an upstream's users","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml get /upstreams/{id}/users","href":"/api-reference/users/list-an-upstreams-users"},{"title":"Add a user to an upstream","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml post /upstreams/{id}/users","href":"/api-reference/users/add-a-user-to-an-upstream"},{"title":"Drop a user's registrations","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml post /upstreams/{id}/revocations","href":"/api-reference/users/drop-a-users-registrations"},{"title":"Delete a user","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml delete /users/{id}","href":"/api-reference/users/delete-a-user"},{"title":"Change a user's password or auth username, or turn it on or off","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml patch /users/{id}","href":"/api-reference/users/change-a-users-password-or-auth-username-or-turn-it-on-or-off"}]},{"group":"Bindings","pages":[{"title":"List registered devices","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml get /bindings","href":"/api-reference/bindings/list-registered-devices"},{"title":"Delete a registered device","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml delete /bindings/{key}","href":"/api-reference/bindings/delete-a-registered-device"},{"title":"Send a device a silent test push","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml post /bindings/{key}/test-push","href":"/api-reference/bindings/send-a-device-a-silent-test-push"}]},{"group":"Push events","pages":[{"title":"List recent push attempts","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml get /push-events","href":"/api-reference/push-events/list-recent-push-attempts"}]},{"group":"TLS","pages":[{"title":"Load the certificate again","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml post /tls/reload","href":"/api-reference/tls/load-the-certificate-again"}]},{"group":"Register bans","pages":[{"title":"List the active REGISTER bans","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml get /register-bans","href":"/api-reference/register-bans/list-the-active-register-bans"},{"title":"Lift a REGISTER ban","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml delete /register-bans/{source}","href":"/api-reference/register-bans/lift-a-register-ban"}]},{"group":"Config","pages":[{"title":"Export the tenant's configuration","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml get /config/export","href":"/api-reference/config/export-the-tenants-configuration"},{"title":"Make the tenant's configuration match a snapshot","deprecated":null,"version":null,"openapi":"/reference/openapi.yaml post /config/sync","href":"/api-reference/config/make-the-tenants-configuration-match-a-snapshot"}]}]}]}]},"basePath":"","title":"Add a PBX - pgw","deploymentId":"dpl_HhUetB7eHHDAmK9T1Teip38TgFx9","buildId":"dpl_HhUetB7eHHDAmK9T1Teip38TgFx9","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-jJHA3WSo.js","utils-DbZn3Mjn.js","cloneDeep-CnBnaSyy.js","_Uint8Array-CMQtTgBR.js","isObject-FP1Yky1u.js","utils-Bl2DvzOJ.js","addUniqueKeysToSchema-BwOLo9p1.js","snippetPresets-BBiPpKa-.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","conditional-requirements-CFM0id0Q.js","ApiExamples-C0px4Tml.js","isEqual-zAyttAAO.js","usePlaygroundInputsStore-Dell6dGw.js","shallow-0VKqkSqN.js","getApiPlaygroundDisplay-CP_ctPEB.js","CodeSnippet-5L35ic0s.js","CodeSnippets-DOXbNhJw.js","Page-DRLI_2Ue.js","getPastedJson-VhzT9m2P.js","icon-CD8_AtCO.js","MethodPill-DGgOMftG.js","DuplicateIcon-DZ6A_EtN.js","createIcon-DUl4oM5f.js","DynamicMarkdown-BGHukeRM.js","SectionHeading-ChrEUs8u.js","axios-vUo_bRtp.js","Markdown-Dj-na-_-.js","dist-C5gjFYHe.js","lib-DuNMoZ05.js","lib-B8HbPgcC.js","katex-YMM-FMeD.js","html-void-elements-mCSPHezU.js","marked.esm-CZWythHk.js","AssistantPageLink-DEBW87tT.js"]}