Viio Sync API SDK for Python

viio-sync-api-sdk contains the generated viio.sync.v1 protobuf contract and an AsyncIO client for authentication and explicit sync-batch lifecycle management.

Install

python -m pip install viio-sync-api-sdk

Python 3.11 and later are supported without an artificial upper minor-version cap. CI validates the minimum version and the latest stable Python release, so the upper tested version advances automatically.

Send a batch

from viio_sync_api import SyncApiAuthentication, SyncApiClient, SyncApiClientOptions
from viio_sync_api.v1 import Account, AccountRecords, GenericAccountDetails, SyncRecordsRequest


async def sync_accounts() -> None:
    options = SyncApiClientOptions(
        endpoint="https://sync.example.com",
        authentication=SyncApiAuthentication.api_key("your-api-key"),
    )

    async with SyncApiClient(options) as client:
        batch = await client.start_batch("installation-id")
        try:
            await batch.write(
                SyncRecordsRequest(
                    accounts=AccountRecords(
                        records=[
                            Account(
                                generic=GenericAccountDetails(
                                    id="account-1",
                                    email="person@example.com",
                                )
                            )
                        ]
                    )
                )
            )
            await batch.complete()
        except BaseException:
            await batch.abort()
            raise

Each write accepts exactly one typed records wrapper. A present empty wrapper represents an intentional empty snapshot:

await batch.write(SyncRecordsRequest(accounts=AccountRecords()))

SyncApiBatchAlreadyInProgressError distinguishes an existing sync. Protocol failures raise SyncApiProtocolError. Native grpc.aio.AioRpcError, cancellation, and timeout errors remain available for retry decisions.

The authenticated generated stub is available as client.grpc_client. Calls through it bypass batch validation.

max_receive_message_size caps individual responses received by this client, while max_send_message_size caps individual requests it sends. The receive limit defaults to 16 MiB to match the .NET SDK; setting either value to None leaves that direction at gRPC's default.

AWS Lambda

The Viio developer portal provides a complete Lambda handler and AWS SAM template. The handler acquires an application token from Microsoft Entra ID, pages through Microsoft Graph users, maps each user to MicrosoftEmployeeDetails, writes a complete employee snapshot, and completes or aborts the Sync API batch. The template configures Amazon EventBridge Scheduler to invoke it every night with cron(0 2 * * ? *).

Grant the Entra application the Microsoft Graph User.Read.All application permission and supply these Lambda environment variables from your secret-management system:

• MICROSOFT_TENANT_ID
• MICROSOFT_CLIENT_ID
• MICROSOFT_CLIENT_SECRET
• VIIO_SYNC_API_ENDPOINT
• VIIO_SYNC_API_KEY
• VIIO_DIRECT_INTEGRATION_INSTALLATION_ID

The example creates and closes the client inside each invocation's event loop. This avoids retaining a gRPC AsyncIO channel across event loops when Lambda reuses a warm execution environment.

grpcio contains native code. When creating a Lambda ZIP or layer on another operating system, ask pip for the matching Linux wheel:

# x86_64
python -m pip install \
  --platform manylinux2014_x86_64 \
  --implementation cp \
  --python-version 3.11 \
  --only-binary=:all: \
  --target package \
  viio-sync-api-sdk

# arm64
python -m pip install \
  --platform manylinux2014_aarch64 \
  --implementation cp \
  --python-version 3.11 \
  --only-binary=:all: \
  --target package \
  viio-sync-api-sdk

Replace 3.11 with the Python version of the target Lambda runtime. The same package can be installed normally in AWS Lambda Python container images. Full API documentation is available at https://developers.viio.io/sync-api.

Authentication and transport security

External integrations use API keys. Viio-managed callers can supply an asynchronous bearer-token provider.

Sync API endpoints must use HTTPS. HTTP is accepted only for loopback endpoints during development. SDK exception messages and representations do not include keys or bearer tokens.

License

MIT