Toolkit Classes

The Function App isolates all external service communication into two toolkit classes. These are the only code that makes outbound network calls to Pexip or Azure services.

PexipToolkit

Location: packages/pexip-sdk/toolkit/PexipToolkit.py

Handles all communication with the Pexip Infinity Management API.

Authentication

PexipToolkit authenticates using OAuth2.0 with a private key JWT (not client secret):

sequenceDiagram
    participant FA as Function App
    participant Pexip as Pexip Management Node

    FA->>Pexip: POST /oauth/token/<br/>(client_id + JWT signed with ES256 key)
    Pexip-->>FA: access_token
    FA->>Pexip: API request<br/>(Authorization: Bearer token)
    Pexip-->>FA: Response
    Note over FA: If 401, auto-regenerates token and retries

The private key (pexip_jwt_key) is stored Base64-encoded in Key Vault and decoded at runtime. The JWT is signed with the ES256 algorithm.

Token auto-refresh

The TokenAuthenticator class (extending httpx.Auth) intercepts 401 responses and automatically regenerates the token before retrying the request. This is transparent to calling code.

Key methods

Method	Purpose
`generate_token()`	Fetches a new OAuth2 token from Pexip using private key JWT
`get_virtual_meeting_rooms()`	Lists or gets specific VMRs from Pexip
`create_virtual_meeting_room()`	Creates a new VMR on Pexip
`update_virtual_meeting_room()`	Patches VMR properties (tag, PIN, etc.)
`delete_virtual_meeting_room()`	Deletes a VMR by ID
`bulk_delete_virtual_meeting_rooms()`	Deletes all non-persistent rooms
`uui_data_parts()`	Decodes hex-encoded UUI data into host + video_call_id

UUI data decoding

The BCSC app passes session identity as hex-encoded UUI data (e.g., 6964264d54497a4e4455324c4463324e54517a4d67;encoding=hex). The toolkit decodes this into:

Host: The IAS environment identifier (e.g., id, idtest, iddev)
Video call ID: The session identifier used to construct the service tag URL

The resulting tag URL follows the pattern: https://{host}.gov.bc.ca/idcheck/protected/video/{video_call_id}

AzureToolkit

Location: packages/pexip-sdk/toolkit/AzureToolkit.py

Handles all Azure service interactions using DefaultAzureCredential (Managed Identity in Azure, CLI/environment credentials locally).

Key methods

Method	Purpose
`get_secret()`	Reads a secret from Azure Key Vault
`patch_secret()`	Writes/updates a secret in Key Vault
`pop_queue_items()`	Pops messages from an Azure Storage Queue
`pop_queue_item()`	Pops a single message
`add_queue_item()`	Adds a message to a queue
`delete_queue_item()`	Deletes a processed queue message
`clear_queue()`	Clears all messages from a queue
`send_to_log_analytics()`	Writes metrics to a Log Analytics workspace

Queue message encoding

Queue messages are Base64-encoded by Azure Storage. The toolkit decodes them transparently - the message_text field in returned messages contains the decoded room name string.

Authentication

AzureToolkit uses DefaultAzureCredential which resolves in order:

In Azure: Managed Identity (no credentials needed)
In devcontainer: Azure CLI credential (az login)
Fallback: Environment variables (AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID)

Shared state pattern

Both toolkits use a _shared_state class variable pattern (similar to Borg/monostate) to share state across instances within the same process. This ensures:

A single httpx.AsyncClient is reused across requests
A single DefaultAzureCredential instance is shared
Token state persists across function invocations within the same worker