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

# Register an app

> Registers an app with its push credentials. iOS apps need the
`apns_*` fields, Android apps need the `fcm_*` fields, and web apps
need `vapid_subject`. A tenant can have one web app. Without
`vapid_private_key_pem`, pgw generates the web app's VAPID key. pgw
checks the format of each credential and encrypts it at rest, but doesn't
contact Apple or Google.




## OpenAPI

````yaml /reference/openapi.yaml post /apps
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:
  /apps:
    post:
      tags:
        - Apps
      summary: Register an app
      description: >
        Registers an app with its push credentials. iOS apps need the

        `apns_*` fields, Android apps need the `fcm_*` fields, and web apps

        need `vapid_subject`. A tenant can have one web app. Without

        `vapid_private_key_pem`, pgw generates the web app's VAPID key. pgw

        checks the format of each credential and encrypts it at rest, but
        doesn't

        contact Apple or Google.
      operationId: createApp
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAppRequest'
            examples:
              ios:
                summary: iOS app
                value:
                  platform: ios
                  bundle_id: com.example.phone
                  apns_team_id: ABCDE12345
                  apns_key_id: ABC123DEFG
                  apns_key_pem: |
                    -----BEGIN PRIVATE KEY-----
                    ...
                    -----END PRIVATE KEY-----
                  apns_environment: sandbox
              android:
                summary: Android app
                value:
                  platform: android
                  bundle_id: com.example.phone
                  fcm_project_id: example-phone
                  fcm_project_number: '123456789012'
                  fcm_service_account_json: '{"type": "service_account", ...}'
              web:
                summary: Web app with a generated VAPID key
                value:
                  platform: web
                  bundle_id: web
                  vapid_subject: mailto:ops@example.com
      responses:
        '201':
          description: The app was registered.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/App'
              examples:
                ios:
                  summary: iOS app
                  value:
                    id: Hf2kP9wQ7mXc3LrN8vBd5g
                    platform: ios
                    bundle_id: com.example.phone
                    apns_team_id: ABCDE12345
                    apns_key_id: ABC123DEFG
                    apns_environment: sandbox
                    delivery_mode: ''
                    managed_refresh_push: ''
                    created_at: '2026-11-02T08:20:00Z'
                android:
                  summary: Android app
                  value:
                    id: Tz6rJ1nY4sKb9WqE2uMc7A
                    platform: android
                    bundle_id: com.example.phone
                    fcm_project_id: example-phone
                    fcm_project_number: '123456789012'
                    delivery_mode: ''
                    managed_refresh_push: ''
                    created_at: '2026-11-02T08:21:00Z'
                web:
                  summary: Web app with a generated VAPID key
                  value:
                    id: Lp5mV8xR3tQw6ZsN1kYc2Q
                    platform: web
                    bundle_id: web
                    vapid_public_key: >-
                      BLseZc6gjHGcA3GUYQxQUER37Ug9ejGZcNX9c_m4VpzC2G14Kedhp53SdKsORC3SCCPyKPq4gqMCTuXVQdAD6xA
                    vapid_subject: mailto:ops@example.com
                    delivery_mode: ''
                    managed_refresh_push: ''
                    created_at: '2026-11-02T08:22:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: |
            An app with the same platform and bundle ID exists, another
            Android app uses the same Firebase project ID or number, or the
            tenant already has a web app.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                bundle:
                  summary: Same platform and bundle ID
                  value:
                    error: an App with this platform and bundle ID exists
                firebase:
                  summary: Same Firebase project
                  value:
                    error: >-
                      an Android App with this Firebase project ID or number
                      exists
                web:
                  summary: A second web app
                  value:
                    error: the tenant already has a web App
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    CreateAppRequest:
      type: object
      additionalProperties: false
      required:
        - platform
        - bundle_id
      properties:
        platform:
          type: string
          enum:
            - ios
            - android
            - web
        bundle_id:
          type: string
          description: >-
            The iOS bundle ID or the Android package name. For a web app, any
            label.
        name:
          type: string
          maxLength: 64
          description: >-
            A name for the app, which log lines show. Without one, log lines
            show the bundle ID. Up to 64 characters, with no control characters.
        apns_team_id:
          type: string
          description: The Apple team ID. Required for iOS.
        apns_key_id:
          type: string
          description: The APNs key ID. Required for iOS.
        apns_key_pem:
          type: string
          description: The contents of the APNs `.p8` key, a PKCS
          writeOnly: true
        apns_environment:
          type: string
          enum:
            - production
            - sandbox
          default: production
          description: Use `sandbox` for builds from Xcode.
        fcm_project_id:
          type: string
          description: >-
            The Firebase project ID. pgw sends pushes to this project. Required
            for Android. Must not be all digits.
        fcm_project_number:
          type: string
          pattern: ^[0-9]*$
          description: >-
            The Firebase project number. Optional, but Linphone identifies its
            project by this number, so a Linphone build needs it.
        fcm_service_account_json:
          type: string
          description: >-
            The contents of the Firebase service account key file. Required for
            Android.
          writeOnly: true
        vapid_subject:
          type: string
          description: >-
            A `mailto:` or `https:` URI that push services can use to contact
            you. Required for web.
        vapid_private_key_pem:
          type: string
          description: A P-256 private key in PEM, PKCS
          writeOnly: true
        delivery_mode:
          $ref: '#/components/schemas/DeliveryMode'
          description: Omit to use the gateway default.
        managed_refresh_push:
          type: string
          enum:
            - ''
            - 'on'
            - 'off'
          description: >-
            Whether pgw sends the app's managed iOS and Android devices a
            refresh push before their registration expires. Omit to use the
            gateway default.
    App:
      type: object
      required:
        - id
        - platform
        - bundle_id
        - delivery_mode
        - managed_refresh_push
        - created_at
      properties:
        id:
          type: string
        platform:
          type: string
          enum:
            - ios
            - android
            - web
        bundle_id:
          type: string
        name:
          type: string
          description: Absent when the app has no name.
        apns_team_id:
          type: string
        apns_key_id:
          type: string
        apns_environment:
          type: string
          enum:
            - production
            - sandbox
        fcm_project_id:
          type: string
        fcm_project_number:
          type: string
        vapid_public_key:
          type: string
          description: >-
            A web app's VAPID public key, in unpadded base64url. Browsers
            subscribe with it.
        vapid_subject:
          type: string
        delivery_mode:
          type: string
          enum:
            - ''
            - provisional
            - always_push
          description: Empty when the app uses the gateway default.
        managed_refresh_push:
          type: string
          enum:
            - ''
            - 'on'
            - 'off'
          description: Empty when the app uses the gateway default.
        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.
    DeliveryMode:
      type: string
      enum:
        - provisional
        - always_push
      description: |
        How pgw sends a call to an app that has an open connection.
        `provisional` sends the call on the connection and pushes if the app
        doesn't respond within `provisional_timeout`. `always_push` pushes for
        every call.
  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.