> ## 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 user to an upstream

> Stores a SIP account for managed mode. pgw encrypts the password with
the tenant's data key and never returns it.




## OpenAPI

````yaml /reference/openapi.yaml post /upstreams/{id}/users
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/{id}/users:
    parameters:
      - name: id
        in: path
        required: true
        description: The upstream ID.
        schema:
          type: string
    post:
      tags:
        - Users
      summary: Add a user to an upstream
      description: |
        Stores a SIP account for managed mode. pgw encrypts the password with
        the tenant's data key and never returns it.
      operationId: createUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
            example:
              username: alice
              password: correct-horse
      responses:
        '201':
          description: The user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              example:
                id: Ws7nK2vP9xLm4QtR6yBc3g
                upstream_id: Ux9cT4mK7pLw2RvN5yQs8g
                username: alice
                enabled: true
                last_seen_at: '2026-11-16T09:30:00Z'
                created_at: '2026-11-16T09:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/UpstreamNotFound'
        '409':
          description: |
            The upstream has a user with this username at this domain, its
            users come from Kamailio, or its domains changed and no longer
            serve the user's domain.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                exists:
                  summary: The username is taken
                  value:
                    error: a user with this username exists on the upstream
                existsAtDomain:
                  summary: The username is taken at this domain
                  value:
                    error: >-
                      a user with this username exists at this domain of the
                      upstream
                kamailio:
                  summary: The upstream's users come from Kamailio
                  value:
                    error: users of this upstream come from Kamailio
                domain:
                  summary: The upstream's domains no longer serve the user's domain
                  value:
                    error: >-
                      every user of an upstream with domains needs a domain that
                      it serves
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    CreateUserRequest:
      type: object
      additionalProperties: false
      required:
        - username
        - password
      properties:
        username:
          type: string
          minLength: 1
          maxLength: 128
          description: |
            The SIP user that apps register as and authenticate to pgw with,
            without control characters. It can't change.
        domain:
          type: string
          description: |
            The domain that the user's apps register to: the upstream's host
            or a name that its domains serve. Required on an upstream with
            `domains`, and refused with 400 on any other. pgw stores it in
            lower case without a trailing dot. It can't change. 1001 at two
            domains is two users.
          example: acme.example.com
        auth_username:
          type: string
          maxLength: 128
          description: |
            The digest username that pgw answers the PBX with, when the PBX
            knows the account by another name than `username`. Apps still
            authenticate to pgw as `username`.
        password:
          type: string
          minLength: 1
          maxLength: 256
          writeOnly: true
        enabled:
          type: boolean
          default: true
    User:
      type: object
      required:
        - id
        - upstream_id
        - username
        - enabled
        - last_seen_at
        - created_at
      properties:
        id:
          type: string
        upstream_id:
          type: string
        domain:
          type: string
          description: Absent on an upstream without domains.
        username:
          type: string
        auth_username:
          type: string
          description: Absent when pgw answers the PBX with the username.
        enabled:
          type: boolean
        last_seen_at:
          type: string
          format: date-time
          description: >-
            When a device last registered as this user, or when the user was
            created if none has.
        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.
  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
    UpstreamNotFound:
      description: The tenant has no upstream with this ID.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: no such upstream
    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.