Viio.SyncApi.Sdk 1.1.0

Viio Sync API SDK for .NET

Viio.SyncApi.Sdk contains the versioned Sync API protobuf contracts, generated gRPC clients and server contracts, and a supported client for authentication and explicit sync-batch lifecycle management. The first release includes viio.sync.v1; future contract majors can be distributed by the same package.

Install

dotnet add package Viio.SyncApi.Sdk

The package targets .NET 10.

Full API documentation is available at https://developers.viio.io/sync-api.

Create a client

API key:

using Viio.SyncApi;

using var client = new SyncApiClient(new SyncApiClientOptions(
    new Uri("https://sync.example.com"),
    SyncApiAuthentication.ApiKey(configuration["SyncApi:ApiKey"]!)));

The Sync API and OAuth token endpoints must use HTTPS. HTTP is accepted only for loopback endpoints during local development. OAuth token endpoint redirects are rejected.

Viio does not currently issue rotating API keys. OAuth 2.0 client credentials and bearer-token authentication are used by Viio-managed callers; they are included so those callers exercise this same SDK, but are not yet available to external integrations. External availability will be documented when it is supported.

Send a batch

using Viio.SyncApi.V1.Contracts;

using var batch = await client.StartBatch(
    directIntegrationInstallationId,
    cancellationToken);

await batch.Write(
    new SyncRecordsRequest
    {
        Accounts = new AccountRecords
        {
            Records =
            {
                new Account
                {
                    Generic = new GenericAccountDetails
                    {
                        Id = "account-1",
                        Email = "person@example.com"
                    }
                }
            }
        }
    },
    cancellationToken);

await batch.Write(
    new SyncRecordsRequest
    {
        Employees = new EmployeeRecords
        {
            Records =
            {
                new Employee
                {
                    Generic = new GenericEmployeeDetails
                    {
                        Id = "employee-1",
                        FullName = "Ada Lovelace",
                        Email = "ada@example.com",
                        Active = true,
                        OrgUnit = "/Engineering"
                    }
                }
            }
        }
    },
    cancellationToken);

await batch.Complete(cancellationToken);

Each write accepts exactly one typed records wrapper. To declare an empty snapshot, send a present empty wrapper:

await batch.Write(
    new SyncRecordsRequest { Accounts = new AccountRecords() },
    cancellationToken);

Every canonical record selects exactly one Data case. Generic is field 1 and carries the provider-neutral record shape; provider-specific cases are added after it without changing the generic contract.

For employees, set a non-empty Id in the selected details payload and exactly one of Generic, Microsoft, Google, Okta, or BambooHr. A request or batch may contain employees from multiple providers. Sync API transforms each provider payload into Viio's canonical employee model after the complete employee snapshot has arrived.

Abort an unsuccessful batch explicitly:

await batch.Abort(cancellationToken);

Writes and terminal operations are rejected after a successful completion or abort. Disposing a batch releases its local synchronization resources; it does not complete or abort the batch.

Errors and advanced access

• SyncApiBatchAlreadyInProgressException reports SyncAlreadyInProgress.
• SyncApiProtocolException reports a server response with success = false.
• SyncApiAuthenticationException reports authentication acquisition failures without including secrets or token response bodies.
• Grpc.Core.RpcException remains available to callers for transport status and retry decisions.

The generated SyncServiceClient is available through SyncApiClient.GrpcClient for advanced use. Direct generated client calls bypass the high-level batch lifecycle validation.

License

Viio.SyncApi.Sdk is licensed under the MIT License.