.NET SDK

Installation

dotnet add package SikkerKey

Requires .NET 8.0+. Single dependency: NSec.Cryptography for Ed25519 signing.

Quick Start

using SikkerKey;

var sk = SikkerKeyClient.Create("vault_abc123");
var secret = await sk.GetSecretAsync("sk_a1b2c3d4e5");

The SDK loads the machine identity from ~/.sikkerkey/vaults/{vaultId}/identity.json, signs every request with the machine's Ed25519 private key, and returns the decrypted value. All data methods are async.

Client Creation

// Explicit vault ID
var sk = SikkerKeyClient.Create("vault_abc123");

// Direct path to identity file
var sk = SikkerKeyClient.Create("/etc/sikkerkey/vaults/vault_abc123/identity.json");

// Auto-detect from SIKKERKEY_IDENTITY env or single vault on disk
var sk = SikkerKeyClient.Create();

Throws ConfigurationException if the identity is missing, the key can't be loaded, or multiple vaults exist without a specified vault ID.

Serverless (Memory-Only Bootstrap)

On a long-lived host the SDK loads a persistent identity from disk. Serverless and other ephemeral or read-only-filesystem environments (Azure Functions, AWS Lambda, Google Cloud Run, and similar) have no identity to persist. SikkerKeyClient.BootstrapInMemoryAsync() handles that case: it generates an Ed25519 keypair in memory, enrolls a short-lived ephemeral machine with an enrollment token, and returns a ready client, without writing anything to disk.

var sk = await SikkerKeyClient.BootstrapInMemoryAsync(
    Environment.GetEnvironmentVariable("SIKKERKEY_VAULT_ID")!,
    Environment.GetEnvironmentVariable("SIKKERKEY_ENROLLMENT_TOKEN")!
);

var dbUrl = await sk.GetSecretAsync("sk_db_prod");

Create an enrollment token in the dashboard and supply its plaintext plus your vault ID. The token only registers an ephemeral machine scoped to the policy you set (projects, secrets, lifetime); it cannot read secrets on its own.

How It Works

• BootstrapInMemoryAsync() enrolls once, when you await it: it generates a keypair in memory, registers an ephemeral machine, and returns a ready client.
• The returned client signs every read with the in-memory private key, exactly like a disk-based client.
• Nothing is written to disk. The private key lives only in process memory and is gone when the process exits.
• The ephemeral machine lives for the lifetime set on the enrollment token. Reading after it expires throws AuthenticationException, so set the token's machine lifetime to suit your workload. The common path is to read secrets at startup and hold the values.

Options

var sk = await SikkerKeyClient.BootstrapInMemoryAsync(
    vaultId,
    token,
    hostname: "worker-1",   // defaults to $HOSTNAME, then "serverless"
    name: "batch-runner"    // overridden if the token defines a name pattern
);

Provisioning the Token for Serverless

When you create the enrollment token for a serverless deployment:

• Set a short machine lifetime (minutes). Each cold start mints a fresh ephemeral machine, and short-lived ones free their slot quickly as they expire.
• Set max-uses high enough for your cold-start and concurrency volume.
• Leave the source-CIDR restriction unset, since serverless egress IPs are dynamic.
• If the vault has an IP allowlist, make sure it permits the platform's egress or leave it off. Enrollment enforces the allowlist.
• Set a name pattern on the token (for example serverless-{uuid8}) so each cold-start machine gets a unique name. A name pattern takes precedence over name. {uuidN} inserts N random characters (4 to 32, default 8); {uuid} inserts 8.

Each live ephemeral machine counts against your plan's machine limit until it expires and is cleaned up. Requires outbound HTTPS.

Reading Secrets

Single Value

var apiKey = await sk.GetSecretAsync("sk_stripe_prod");

Structured (Multiple Fields)

var fields = await sk.GetFieldsAsync("sk_db_prod");
var host = fields["host"];       // "db.example.com"
var password = fields["password"]; // "hunter2"

Throws SecretStructureException if the secret value is not a JSON object.

Single Field

var password = await sk.GetFieldAsync("sk_db_prod", "password");

Throws FieldNotFoundException if the field doesn't exist. The error message includes available field names.

Listing Secrets

// All secrets this machine can access
var secrets = await sk.ListSecretsAsync();
foreach (var s in secrets)
    Console.WriteLine($"{s.Id}: {s.Name}");

// Secrets in a specific project
var projectSecrets = await sk.ListSecretsByProjectAsync("proj_abc123");

Returns List<SecretListItem> with Id, Name, FieldNames (nullable), and ProjectId (nullable).

Export

// All secrets as a flat dictionary
var env = await sk.ExportAsync();

// Scoped to a project
var env = await sk.ExportAsync("proj_production");

// Inject into environment
foreach (var (key, value) in await sk.ExportAsync())
    Environment.SetEnvironmentVariable(key, value);

Structured secrets are flattened: SECRET_NAME_FIELD_NAME.

Watching for Changes

Watch secrets for real-time updates. When a secret is rotated, updated, or deleted, the callback fires with the new value.

sk.Watch("sk_db_credentials", (e) =>
{
    switch (e.Status)
    {
        case WatchStatus.Changed:
            // e.Value has the new value
            // e.Fields has parsed key-value pairs for structured secrets
            Database.ConfigureCredentials(e.Fields!["username"], e.Fields["password"]);
            break;
        case WatchStatus.Deleted:
            Console.WriteLine("Secret deleted");
            break;
        case WatchStatus.AccessDenied:
            Console.WriteLine("Access revoked");
            break;
        case WatchStatus.Error:
            Console.WriteLine($"Error: {e.Error}");
            break;
    }
});

Polling starts automatically on the first Watch() call and runs on a background task. Default interval is 15 seconds (server enforces a 10-second minimum).

sk.SetPollInterval(30); // seconds
sk.Unwatch("sk_db_credentials"); // stop watching one secret
sk.Close(); // stop all watches

SikkerKeyClient implements IDisposable for automatic cleanup with using blocks.

Multi-Vault

var prod = SikkerKeyClient.Create("vault_a1b2c3");
var staging = SikkerKeyClient.Create("vault_x9y8z7");

var prodKey = await prod.GetSecretAsync("sk_api_key");
var stagingKey = await staging.GetSecretAsync("sk_api_key");

List Registered Vaults

var vaults = SikkerKeyClient.ListVaults();
// ["vault_a1b2c3", "vault_x9y8z7"]

Static method, synchronous.

Identity Resolution

1. Explicit path - starts with / or contains identity.json
2. Vault ID - looks up ~/.sikkerkey/vaults/{vaultId}/identity.json
3. SIKKERKEY_IDENTITY env - path to identity file
4. Auto-detect - single vault on disk

The vault_ prefix is added automatically if not present. Override base directory with SIKKERKEY_HOME.

Error Handling

using SikkerKey;

try
{
    var secret = await sk.GetSecretAsync("sk_nonexistent");
}
catch (NotFoundException)
{
    // 404 - secret doesn't exist
}
catch (AccessDeniedException)
{
    // 403 - machine not approved or no grant
}
catch (AuthenticationException)
{
    // 401 - invalid signature or unknown machine
}
catch (ApiException e)
{
    // Any other HTTP error
    Console.WriteLine(e.HttpStatus);
}

Exception Hierarchy

SikkerKeyException
├── ConfigurationException      - identity/key issues
├── SecretStructureException    - secret is not a JSON object (GetFieldsAsync)
├── FieldNotFoundException      - field not in structured secret (GetFieldAsync)
└── ApiException                - HTTP error (has HttpStatus property)
    ├── AuthenticationException - 401
    ├── AccessDeniedException   - 403
    ├── NotFoundException       - 404
    ├── ConflictException       - 409
    ├── RateLimitedException    - 429
    └── ServerSealedException   - 503

Properties

Read-only.

Method Reference

Retry Behavior

429 and 503 responses are retried up to 3 times with exponential backoff (1s, 2s, 4s). Each retry uses a fresh timestamp and nonce. Network errors (HttpRequestException, TaskCanceledException) are also retried.

Environment Variables

Dependencies

All other functionality uses .NET built-ins: System.Net.Http, System.Text.Json, System.Security.Cryptography.

Types

public record SecretListItem(string Id, string Name, string? FieldNames, string? ProjectId);

All HTTP requests have a 15-second timeout. HTTPS enforced for non-localhost.