ZEDAL .NET SDK Integration Guide¶

The ZEDAL .NET SDK provides a comprehensive, type-safe interface for integrating .NET applications with the ZEDAL document management platform. Built on gRPC and Protocol Buffers, it offers high-performance communication with robust error handling and authentication mechanisms.

Prerequisites¶

.NET Standard 2.0 or higher
Visual Studio 2019 or later / Visual Studio Code with C# extension
ZEDAL Subscriber Credentials (contact ZEDAL sales to obtain)

Installation¶

Install the ZEDAL SDK via NuGet Package Manager:

Package Manager Console¶

Install-Package Zedal.Sdk

.NET CLI¶

dotnet add package Zedal.Sdk

PackageReference (in .csproj)¶

<PackageReference Include="Zedal.Sdk" Version="[latest-version]" />

Core Concepts¶

Authentication Flow¶

The ZEDAL SDK uses a two-token authentication system:

Access Token: Short-lived token (120 minutes) for API requests
Refresh Token: Long-lived token (180 days) for session continuation

Target Systems¶

ZEDAL provides different environments for development and production:

TargetSystem.Test: Test environment for development and testing
TargetSystem.Preview: Staging environment, can be used to test upcoming features
TargetSystem.Production: Live production environment (demo.live.zedal.de should be used for integration testing)

Basic Usage¶

1. Initial Setup and Authentication¶

using Zedal.Sdk;
using Zedal.Sdk.Authentication;

// Client identification - visible in ZEDAL portal session overview
var clientName = "my-integration-app";
var clientVersion = "1.0.0";

// Initialize client for development environment
var zedalClient = new ZedalClient(TargetSystem.Production, clientName, clientVersion)
{
    Auth = { DefaultTimeout = 30 } // Set timeout in seconds
};

2. Provider Discovery and Selection¶

can be skipped if you know your provider id

// Discover available ZEDAL providers (no authentication required)
var providerList = await zedalClient.ListProvider();

// Select appropriate provider (typically done through user interface)
var selectedProvider = providerList.FirstOrDefault(p => p.Name == "demo.live.zedal.de");
if (selectedProvider == null)
{
    throw new InvalidOperationException("Required provider not found");
}

3. Session Management¶

Creating a New Session¶

try
{
    // Credentials provided by ZEDAL sales team
    var subscriberId = "<your-subscriber-id>";
    var accountPassword = "<your-account-password>";
    var appToken = new AppToken("<your-app-token>");

    // Establish authenticated session
    await zedalClient.CreateSession(
        selectedProvider.Id, 
        subscriberId, 
        string.Empty, // Additional parameter (usually empty)
        accountPassword, 
        appToken
    );

    // Store refresh token for session persistence
    var refreshToken = zedalClient.Auth.RefreshToken;
    // use accessToken on further api calls unrelated to the sdk
    // the sdk uses the accessToken automatically
    var accessToken = zedalClient.Auth.AccessToken;

    Console.WriteLine("Session created successfully");
}
catch (RpcException ex)
{
    Console.WriteLine($"Authentication failed: {ex.Message}");
    // Handle authentication errors
}

Continuing an Existing Session¶

// Resume session using stored refresh token
var storedRefreshToken = GetStoredRefreshToken(); // Your storage implementation

try
{
    await zedalClient.ContinueSession(storedRefreshToken);

    // Update stored tokens (new tokens are generated)
    var newRefreshToken = zedalClient.Auth.RefreshToken;
    var newAccessToken = zedalClient.Auth.AccessToken;

    StoreTokensSecurely(newRefreshToken, newAccessToken); // Your storage implementation
}
catch (RpcException ex)
{
    Console.WriteLine($"Session continuation failed: {ex.Message}");
    // Fall back to creating new session
}

4. Token Lifecycle Management¶

// Subscribe to token refresh events
zedalClient.SetAccessTokenChanged(tokens =>
{
    // Critical: Persist new refresh token for session continuity
    StoreTokensSecurely(tokens.RefreshToken, tokens.AccessToken);

    Console.WriteLine("Tokens refreshed automatically");
});

Token Lifetimes: - Refresh Token: 180 days from creation - Access Token: 120 minutes from creation

Important: The SDK automatically refreshes access tokens when they expire. Always persist the new refresh token when the callback is triggered.

Session Cleanup¶

// Properly end session when done (invalidates refresh token)
try
{
    await zedalClient.EndSession();
    Console.WriteLine("Session ended successfully");
}
catch (Exception ex)
{
    Console.WriteLine($"Error ending session: {ex.Message}");
}
finally
{
    // Clean up stored tokens
    ClearStoredTokens();  // Your storage implementation
}

Complete Integration Example¶

var clientName = "sample-sdk-client"; // the name is visible in the session overview of the zedal-portal
var clientVersion = "0.0.1-preview1234";
var subscriberId = "<contactSalesToGetOne>";
var accountPass = "<contactSalesToGetOne>";
var appToken = new AppToken("<contactSalesToGetOne>");

// Create instance, select the Test system with TargetSystem.Development
var zedalClient = new ZedalClient(TargetSystem.Production, clientName, clientVersion) { Auth = { DefaultTimeout = 10 } };

// Lists all the ZedalClient instances on TargetSystem.Development, this requires no active login
var providerList = await zedalClient.ListProvider();

// Select a provider. This should be selected through the GUI.
var prov = providerList.First(x => x.Name == "demo.live.zedal.de");

// Core Services are federated, the right server must be selected by the ID in MetaData, here (devel.Id)
// Proceed with login to the system with your Zedal user credentials
await zedalClient.CreateSession(prov.Id, subscriberId, string.Empty, accountPass, appToken);

// This RefreshToken represents a session and can be used for further logins
var refreshToken = zedalClient.Auth.RefreshToken;
var accessToken = zedalClient.Auth.AccessToken;

// Lifetimes (subject to change)
// RefreshToken: now + 180 * 24 h
// AccessToken: now + 120 min

// Note: If the same session is to be continued later, the logout function must not be used as this will destroy the token
// At any point during the JWT's lifetime you can reuse the session by logging back in with your RefreshToken
// The token itself is used when logging in and a new one is generated
await zedalClient.ContinueSession(refreshToken);
refreshToken = zedalClient.Auth.RefreshToken;
accessToken = zedalClient.Auth.AccessToken;

// Store the RefreshToken in secure local storage to continue this session later

// ZedalClient-SDK refreshes its AccessToken internally when the lifetime expires. Whenever an AccessToken is generated, a new RefreshToken and AccessToken are generated.
// You can subscribe to this callback to get notified when the tokens change.
// If registered, it will be triggered whenever the Zedal-SDK updates the tokens internally.
zedalClient.SetAccessTokenChanged(tokens =>
{
    /* Hook to intercept RefreshToken changes, every new RefreshToken must be persisted for session resumption */
});

// Work with the documents!
var doc = await zedalClient.Documents.GetNextDocument();

// Logging out. This clears the session and invalidates the RefreshToken
await zedalClient.EndSession();