Overview & Process Flow

The Pexip SDK is an Azure Function App (packages/pexip-sdk/) that serves as the sole server-side intermediary between API consumers and the Pexip Infinity platform. No other surface in this repository communicates directly with the Pexip Management API.

Responsibilities

Concern	Implementation
VMR lifecycle (create, read, update, delete)	FastAPI HTTP endpoints
Room pool management	Azure Storage Queues
Pexip Management API auth	OAuth2.0 JWT (client credentials)
Event processing	Pexip event sink webhook
Garbage collection	Timer-triggered function (10 min)
Metrics collection	Timer-triggered function (5 min)
Secrets access	Azure Key Vault via Managed Identity

Room creation flow

The most critical path - what happens when the BCSC app requests a new video session:

sequenceDiagram
    participant BCSC as BCSC Mobile App
    participant IAS as IDIM Video API
    participant Entra as Microsoft Entra ID
    participant APIM as API Management
    participant FA as Function App
    participant Queue as Storage Queue
    participant Pexip as Pexip Management API

    BCSC->>IAS: Start video session
    IAS->>Entra: POST /oauth2/v2.0/token
    Entra-->>IAS: access_token
    IAS->>APIM: POST /room/create?uuiData=...
    APIM->>FA: Forward (validated)
    FA->>Queue: Pop item from room-creation-queue
    Queue-->>FA: Room name
    FA->>Pexip: PATCH /conference/{id} (set tag URL)
    Pexip-->>FA: 200 OK
    FA-->>IAS: ConstrainedConference response
    Note over FA: Background tasks:
    FA->>Pexip: POST /conference (create replacement room)
    FA->>Queue: Add new room name to queue
    IAS-->>BCSC: Room alias + guest PIN
    BCSC->>Pexip: WebRTC connect (conference node)

Step-by-step

1. IDIM Video API authenticates with Entra ID and sends POST /room/create with hex-encoded UUI data
2. API Management validates the OAuth token and forwards to the Function App
3. Function App pops a room name from the room-creation-queue (pre-provisioned pool)
4. Function App decodes the UUI data into a service tag URL and patches the room’s tag property on Pexip
5. Function App returns the room details (alias, guest PIN, tag) to the caller
6. In the background: creates a replacement room on Pexip and adds it to the queue (maintaining pool depth)
7. BCSC app uses the alias and guest PIN to connect via WebRTC to the Pexip Conference Node

Room deletion flow

Rooms are deleted through two mechanisms:

graph TD
    subgraph "Primary: Event Sink"
        A[Conference ends on Pexip] -->|POST /public/event_sink| B[Room name added to deletion queue]
        B --> C[Garbage collector picks up after 10 min]
        C --> D[DELETE room on Pexip]
    end

    subgraph "Fallback: Explicit Delete"
        E[IDIM calls DELETE /room/name] --> F[Function App gets room ID]
        F --> G[DELETE room on Pexip immediately]
    end

Module structure

packages/pexip-sdk/
├── function_app.py          # Azure Functions entry point + timer triggers
├── api/
│   ├── public.py            # /public/* endpoints (event_sink, health, public room get)
│   └── private.py           # /room/* endpoints (CRUD, bulk operations)
├── toolkit/
│   ├── PexipToolkit.py      # Pexip Management API client (OAuth2 JWT auth)
│   └── AzureToolkit.py      # Azure Storage Queue + Key Vault operations
├── models/
│   ├── model.py             # Pydantic models (Conference, Settings, etc.)
│   └── responses.py         # OpenAPI response examples
├── middlewares/
│   ├── exceptions.py        # Global exception handler
│   └── process_time.py      # Request timing middleware
└── tests/
    └── test_PexipToolkit.py  # Unit tests

Key design decisions

• Pre-provisioned room pool: Rooms are created ahead of time and stored in a queue. This avoids latency on the critical path - POST /room/create pulls an existing room rather than creating one synchronously.
• Background replenishment: After serving a room, a new one is created asynchronously (via BackgroundTasks) to maintain pool depth.
• 10-minute deletion delay: The garbage collector waits 10 minutes before deleting a room from the deletion queue, preventing race conditions where a room appears “ended” briefly during reconnection.
• Persistent rooms excluded: Rooms prefixed with test_ or vkiosk_ are never garbage-collected (used for internal testing).