ScanUpload.Api.Client – .NET Integration Guide

ScanUpload enables the integration and the ability to use QR codes to scan and upload files directly from a mobile device to your webapp. This guide explains how to integrate ScanUpload.Api.Client into a modern or legacy .NET application. The client library targets .NET Standard 2.1, making it compatible with:

• .NET 6+
• .NET 7
• .NET 8
• .NET 9
• .NET 10 (preview)
• ASP.NET Core applications
• Older supported .NET runtimes that support .NET Standard 2.1

Front-end integrations

This official client library is designed to work seamlessly with certain ScanUpload front-end components, such as:

• ScanUpload.QrCodeGenerator.React – ScanUpload Qr code generator for React applications

Prerequisites

• .NET SDK
• A ScanUpload account
• A ScanUpload Client ID and Client Secret

dotnet new webapi -n ScanUploadExample
cd  ScanUploadExample

This works for:

• .NET 6+
• .NET 9 / 10 previews
• Existing ASP.NET Core projects

Install the ScanUpload API client

dotnet add package ScanUpload.Api.Client --version 1.0.0
dotnet add package Microsoft.Extensions.Http.Resilience

Using Visual Studio

1. Right‑click the project → Manage NuGet Packages
2. Enable Include prerelease
3. Search for ScanUpload.Api.Client
4. Install the latest version
5. Install Microsoft.Extensions.Http.Resilience (optional)

Configuration

Add the ScanUpload configuration section to appsettings.json:

  "ScanUploadProxy": {
    "ScanUploadTargetBaseUrl": "https://hub.scanupload.net/api/front-end",
    "ScanUploadRoutePrefix": "/scanupload-api",
    "ScanUploadTokenRoute": "/scanupload-api/token",
    "ScanUploadStripRoutePrefix": true,
    "ScanUploadRequestTimeout": "00:01:30",
    "ScanUploadHeadersToForward": [
      "Authorization",
      "Content-Type",
      "User-Agent",
      "X-Requested-With",
      "X-API-Key"
    ],
    "ScanUploadApiClient": {
      "ScanUploadBaseUrl": "https://hub.scanupload.net"
    },
    "ScanUploadAdditionalHeaders": {
      "X-Forwarded-By": "ScanUpload-Proxy",
      "X-Proxy-Version": "1.0"
    },
    "KeycloakServerUrl": "https://identity.scanupload.net/",
    "KeycloakRealm": "scanupload-hub",
    "KeycloakScope": "openid profile email scanupload.hub"
  }

🔐 For local development, store secrets using User Secrets instead of committing them to source control.

Configure user secrets

Please use ASP.NET Core user secrets for local development. These values are not committed to source control.

dotnet user-secrets init

Add your ScanUpload credentials:

dotnet user-secrets set "ScanUploadProxy:KeycloakClientId"  "your-client-id"  
dotnet user-secrets set "ScanUploadProxy:KeycloakClientSecret"  "your-client-secret"

This creates a secrets.json file in your local user profile, for example:

{
  "ScanUploadProxy": {
    "KeycloakClientId": "your-client-id",
    "KeycloakClientSecret": "your-client-secret"
  }
}

Configure services in Program.cs

Register ScanUpload services

builder.Services.Configure<ScanUploadProxyOptions>(
    builder.Configuration.GetSection("ScanUploadProxy")
);

builder.Services.AddScanUploadProxy(
    builder.Configuration.GetSection("ScanUploadProxy").Bind,
    builder =>
    {
        builder.AddStandardResilienceHandler();
    }
);

builder.Services.AddScanUploadApiClient(
    builder.Configuration,
    builder =>
    {
        builder.AddStandardResilienceHandler();
    }
);

Enable the ScanUpload proxy middleware

Add the middleware after routing and before endpoints:

app.UseScanUploadProxy();

Minimal Program.cs example

using ScanUpload.Api.Client.Extensions;
using ScanUpload.Api.Client.Interface;
using ScanUpload.Api.Client.KeycloakIntegration;

var builder = WebApplication.CreateBuilder(args);

builder.Services.Configure<ScanUploadProxyOptions>(
    builder.Configuration.GetSection("ScanUploadProxy")
);

builder.Services.AddScanUploadProxy(
    builder.Configuration.GetSection("ScanUploadProxy").Bind,
    builder =>
    {
        builder.AddStandardResilienceHandler();
    }
);

builder.Services.AddScanUploadApiClient(
    builder.Configuration,
    builder =>
    {
        builder.AddStandardResilienceHandler();
    }
);

builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

app.UseHttpsRedirection();
app.UseAuthorization();

app.UseScanUploadProxy();

app.MapControllers();

app.Run();

Compatibility notes

• The client targets .NET Standard 2.1
• Works with both modern and older ASP.NET Core applications
• Safe to use in long‑term support (LTS) environments
• Fully compatible with Docker and cloud deployments

Resilience and reliability (Optional)

The client integrates with Microsoft.Extensions.Http.Resilience, providing:

• Automatic retries
• Timeouts
• Circuit breakers
• Transient fault handling

This ensures reliable communication with the ScanUpload API in production.