QuantumAPI.Client 0.20.0

QuantumAPI.Client — .NET SDK

Official .NET SDK for the QuantumAPI quantum-safe encryption, key management, and secrets management platform.

Documentation: https://docs.quantumapi.eu/sdk/dotnet

Installation

dotnet add package QuantumAPI.Client --version 0.1.0-beta

Quick Start

Direct instantiation

using QuantumAPI.Client;
using QuantumAPI.Client.Models.Encryption;
using QuantumAPI.Client.Models.Secrets;

var client = new QuantumAPIClient("qapi_your_api_key");

// Encrypt data
var encrypted = await client.Encryption.EncryptAsync(new EncryptRequest
{
    Plaintext = "secret data",
    KeyId = Guid.Parse("550e8400-e29b-41d4-a716-446655440000")
});

// Decrypt using the opaque payload (simplest approach)
var decrypted = await client.Encryption.DecryptAsync(new DecryptRequest
{
    EncryptedPayload = encrypted.EncryptedPayload
});

Console.WriteLine(decrypted.Plaintext); // "secret data"

// Store a secret
var secret = await client.Secrets.CreateAsync(new CreateSecretRequest
{
    Name = "database_password",
    Value = "super_secret",
    Labels = new[] { "env=production" }
});

ASP.NET Core DI integration

// Program.cs
builder.Services.AddQuantumAPI(options =>
{
    options.ApiKey = builder.Configuration["QuantumAPI:ApiKey"];
});

// Then inject QuantumAPIClient anywhere
public class MyService
{
    private readonly QuantumAPIClient _quantum;

    public MyService(QuantumAPIClient quantum) => _quantum = quantum;

    public async Task<string> EncryptAsync(string plaintext)
    {
        var result = await _quantum.Encryption.EncryptAsync(new EncryptRequest
        {
            Plaintext = plaintext
        });
        return result.EncryptedPayload;
    }
}

Configuration via appsettings.json

{
  "QuantumAPI": {
    "ApiKey": "qapi_xxx",
    "BaseUrl": "https://api.quantumapi.eu",
    "MaxRetries": 3,
    "Timeout": "00:00:30"
  }
}

builder.Services.AddQuantumAPI(builder.Configuration.GetSection("QuantumAPI"));

Modules

Key Features

• Quantum-safe encryption — ML-KEM-768 + AES-256-GCM hybrid encryption
• Post-quantum signatures — ML-DSA-65, plus RSA-PSS and ECDSA
• Bearer token auth — API key sent as Authorization: Bearer <key>
• Automatic retries — exponential backoff on 429/500/502/503/504
• Rate limit tracking — warnings at low remaining count, RateLimitException on 429
• Typed exceptions — QuantumApiException, RateLimitException, AuthenticationException, NotFoundException, ForbiddenException
• Pagination — PagedList<T> with Page, PageSize, TotalCount, HasMore
• Webhook verification — HMAC-SHA256 via WebhookVerifier.VerifySignature()
• Structured logging — ILogger integration, opt-in detailed logging
• Full async/await — all I/O is async
• DI ready — services.AddQuantumAPI(options => ...)
• Configurable — IOptions<QuantumAPIOptions>

Encryption

Encrypt

var result = await client.Encryption.EncryptAsync(new EncryptRequest
{
    Plaintext = "sensitive value",
    Encoding = "utf8",          // or "base64" for binary data
    KeyId = myKeyId,            // optional; uses tenant default if omitted
    Algorithm = "ML-KEM-768",   // ML-KEM-768 (default), ML-KEM-512, ML-KEM-1024
    AdditionalData = null       // optional AAD (base64)
});
// result.EncryptedPayload — opaque payload for /decrypt
// result.Ciphertext, .EncapsulatedKey, .Nonce, .Tag — raw components

Decrypt

// Simple: pass the opaque payload from the encrypt response
var decrypted = await client.Encryption.DecryptAsync(new DecryptRequest
{
    EncryptedPayload = result.EncryptedPayload
});

// Advanced: pass individual components
var decrypted2 = await client.Encryption.DecryptAsync(new DecryptRequest
{
    Ciphertext = result.Ciphertext,
    EncapsulatedKey = result.EncapsulatedKey,
    Nonce = result.Nonce,
    Tag = result.Tag,
    KeyId = result.KeyId,
    KeyVersion = result.KeyVersion
});

Sign and Verify

var dataBase64 = Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes("data to sign"));

var signed = await client.Encryption.SignAsync(new SignRequest
{
    Data = dataBase64,
    KeyId = signingKeyId,
    Algorithm = "ML-DSA-65"   // auto-detected from key type for classical keys
});

var verified = await client.Encryption.VerifyAsync(new VerifyRequest
{
    Data = dataBase64,
    Signature = signed.Signature,
    KeyId = signingKeyId
});
Console.WriteLine(verified.IsValid); // true

Key Management

// Generate a PQC encryption key
var key = await client.Keys.GenerateAsync(new GenerateKeyRequest
{
    Name = "my-encryption-key",
    KeyType = KeyType.Encryption,
    Algorithm = "ML-KEM-768",
    SetAsDefault = true
});

// List keys (paginated)
var keys = await client.Keys.ListAsync(new PaginationOptions { Page = 1, PageSize = 20 });

// Rotate a key
var rotated = await client.Keys.RotateAsync(key.Id);

// Schedule for deletion (with grace period)
await client.Keys.ScheduleDeletionAsync(key.Id);

Secrets Management

// Create a secret
var secret = await client.Secrets.CreateAsync(new CreateSecretRequest
{
    Name = "db-password",
    Value = "super_secret_123",
    ContentType = "password",
    Labels = new[] { "env=prod", "service=api" }
});

// Retrieve (includes decrypted value)
var fetched = await client.Secrets.GetAsync(secret.Id);

// Update value (creates new version)
await client.Secrets.UpdateValueAsync(secret.Id, "new_password_456");

// List all versions
var versions = await client.Secrets.ListVersionsAsync(secret.Id);

// Delete permanently
await client.Secrets.DeleteAsync(secret.Id);

Webhook Verification

using QuantumAPI.Client.Extensions;

// In an ASP.NET Core controller or minimal API
app.MapPost("/webhooks/quantum", async (HttpRequest req) =>
{
    var body = await new StreamReader(req.Body).ReadToEndAsync();
    var payload = System.Text.Encoding.UTF8.GetBytes(body);
    var signature = req.Headers[WebhookVerifier.SignatureHeader].ToString();

    if (!WebhookVerifier.VerifySignature(payload, signature, webhookSecret))
    {
        return Results.Unauthorized();
    }

    // Process verified webhook event...
    return Results.Ok();
});

Error Handling

using QuantumAPI.Client.Exceptions;

try
{
    var result = await client.Encryption.EncryptAsync(request);
}
catch (RateLimitException ex)
{
    Console.WriteLine($"Rate limited. Retry after {ex.RetryAfter?.TotalSeconds}s");
    Console.WriteLine($"Limit: {ex.Limit}, Remaining: {ex.Remaining}");
}
catch (AuthenticationException)
{
    Console.WriteLine("Invalid API key");
}
catch (NotFoundException)
{
    Console.WriteLine("Key not found");
}
catch (ForbiddenException)
{
    Console.WriteLine("API key lacks required scope");
}
catch (QuantumApiException ex)
{
    Console.WriteLine($"API error {ex.StatusCode}: {ex.ErrorCode} — {ex.Message}");
}

Rate Limit Status

var status = client.Health.GetRateLimitStatus();
Console.WriteLine($"{status.Remaining}/{status.Limit} requests remaining");
Console.WriteLine($"Resets at {status.ResetAt:u}");

Configuration Reference

Requirements

• .NET 8.0 or .NET 9.0
• Microsoft.Extensions.DependencyInjection.Abstractions ≥ 8.0
• Microsoft.Extensions.Http ≥ 8.0
• Microsoft.Extensions.Logging.Abstractions ≥ 8.0

License

MIT — Copyright © 2026 QuantumAPI