SDK Overview

SikkerKey SDKs give applications read-only access to secrets through a dedicated machine identity. They place secret retrieval directly in your application while preserving the vault’s project membership, secret grants, access policies, IP allowlist, and audit trail.

Official SDKs are available for Go, Python, Node.js, .NET, Kotlin, and PHP. They share the same authentication and secret-access model, with APIs shaped to feel natural in each language.

#Choose an SDK

• Go SDK — applications and services written in Go.

• Python SDK — Python services, scripts, workers, and data workloads.

• Node.js SDK — server-side JavaScript and TypeScript on Node.js.

• .NET SDK — .NET applications using C# or another .NET language.

• Kotlin SDK — Kotlin and JVM applications on Java 17 or newer.

• PHP SDK — PHP services and web applications.

#Shared SDK capabilities

Every official SDK can:

• Read standard secrets by passing a secret ID such as sk_....

• Read structured secrets as a field map or request one named field.

• List accessible secrets for the machine, including project and structured-field metadata.

• Limit discovery to a project by providing a project ID such as proj_....

• Export accessible values as a flat collection of environment-style names and values.

• Use persistent machine identities provisioned on a host.

• Enroll ephemeral machines in memory for short-lived or read-only environments.

• Use an optional encrypted fallback cache during temporary network or service outages.

• Return specific errors for configuration, authentication, access denial, missing secrets, conflicts, rate limits, sealed service state, and invalid structured-secret access.

• Work with more than one vault by creating a separate client for each vault identity.

Go, Python, Node.js, .NET, and Kotlin also include change watching for selected secrets. PHP applications can retrieve values again on a schedule chosen by the application.

#How SDK authentication works

An SDK client represents one machine identity in one vault. Each request is signed with that machine’s Ed25519 private key and includes a fresh timestamp and nonce. The private key remains on the machine and is not sent with the request.

SikkerKey verifies the signature, resolves the machine’s current access, and returns a secret only when the machine can reach its project and has the required secret grant. Changes to project membership, secret grants, access policies, machine status, or machine lifetime are evaluated by subsequent requests.

The SDKs use machine authentication rather than a dashboard user session. This gives the workload its own identity and keeps application access separate from the credentials used by team members.

#Choose an identity model

Persistent machine identity

Use a standard or temporary machine identity for a host where the identity can be provisioned and protected on disk. By default, SDKs resolve identities under:

~/.sikkerkey/vaults/vault_.../identity.json

A client can be created from a vault ID, an explicit path to identity.json, or automatic identity detection.

Automatic detection follows the same order across the SDKs:

1. Use the file named by SIKKERKEY_IDENTITY when the variable is set.

2. Otherwise, use the only registered vault identity in the default identity directory.

3. When several vaults are registered, select a vault ID or identity path explicitly.

Set SIKKERKEY_HOME when the identity directory should live somewhere other than the current user’s home directory:

export SIKKERKEY_HOME=/var/lib/sikkerkey

In-memory ephemeral identity

Use in-memory bootstrap for serverless functions, jobs, containers with read-only filesystems, and other short-lived workloads. The SDK generates an Ed25519 key pair in memory, enrolls an ephemeral machine with an enrollment token, and returns a ready-to-use client.

The private key remains in the process and disappears when the process exits. The resulting machine follows the enrollment token’s access scope, usage limit, hostname requirements, naming rule, and machine lifetime.

#Read secrets

Standard secrets

Use the language’s complete-value method—such as getSecret, get_secret, or GetSecretAsync—with a secret ID. The returned value is a string.

Keep the client available for the lifetime of the application rather than rebuilding it for every read. This reuses the loaded identity and lets watchers and fallback settings remain attached to one client.

Structured secrets

Each SDK provides two structured-secret patterns:

• Get all fields returns a language-native string map or dictionary.

• Get one field returns the requested value and produces a field-specific error when the field is absent.

The SDK first reads the complete secret and then validates that it contains a structured object. Use field access when the application needs only one part of a credential, such as username, password, or host.

#Discover and export accessible secrets

List methods return metadata for secrets the machine can access. Metadata includes the secret ID, display name, optional structured-field information, and owning project when available. Listing does not return secret values.

Use project-filtered listing when an application should discover secrets within one proj_... scope.

Export retrieves accessible values and returns a flat string map suitable for application configuration. Names are converted to uppercase environment-style keys. Spaces and punctuation become underscores, and structured fields are appended to the secret name.

API_KEY
DATABASE_CREDENTIALS_HOST
DATABASE_CREDENTIALS_USERNAME
DATABASE_CREDENTIALS_PASSWORD

Pass a project ID to the export method to limit the returned values to one project. Treat the resulting collection as secret-bearing application data.

#Continue through temporary outages

Every SDK includes the same optional encrypted fallback cache. It is disabled until the application enables it.

After enablement, successful direct secret reads are stored as separate encrypted entries beneath the selected vault’s identity directory. Reads of structured fields use the same complete-value path and populate the cache as well.

Cache entries use AES-256-GCM with a key derived from the machine’s Ed25519 identity and vault ID. Each entry is bound to its machine, vault, secret ID, and cache time. A copied, swapped, or modified entry cannot be used without the matching identity.

The cache format is shared by all official SDKs and the SikkerKey CLI, allowing processes that use the same machine identity and identity directory to use compatible entries.

When fallback is allowed

A cached value may be used after a network failure, request timeout, or gateway and origin-connectivity response indicating that the retrieval service cannot be reached.

Authentication failures, revoked access, access denials, deleted or missing secrets, rate limits, and other authoritative responses are returned to the application. They are not replaced with cached values.

Control freshness and observability

SDKs accept an optional maximum cache age. Once an entry exceeds that age, it is not used as a fallback. Without a maximum age, entries have no automatic SDK-side expiry.

Provide the fallback callback when the application should record that a cached value was served and when it was stored. Keep secret values out of those records.

#React to secret changes

The Go, Python, Node.js, .NET, and Kotlin SDKs can watch selected secrets. Watching polls for changes every 15 seconds by default, with a minimum configurable interval of 10 seconds.

A watcher can report that a secret:

• Changed — the event includes the current value and parsed fields when the value is structured.

• Was deleted — the SDK stops watching that secret.

• Became inaccessible — the SDK stops watching after access is removed.

• Could not be refreshed — SDKs that expose error events provide the failure to the callback; transient polling behavior is described on each language page.

Use the SDK’s unwatch or close method to stop polling. Keep callbacks short and hand slow work to the language’s worker, executor, queue, or asynchronous task system.

PHP does not start a background watcher. A PHP application that needs refreshed values can call the read method again on its own scheduler or request lifecycle.

#Retries, timeouts, and errors

SDK requests use a 15-second network timeout. Temporary transport failures and HTTP 429 or 503 responses are retried up to three times with increasing delays.

Each language exposes a common family of errors using its normal naming conventions:

Handle specific error types when the application can take a meaningful action. For example, retry later after rate limiting, stop a workload after authentication failure, or surface a configuration check when an identity file cannot be loaded.

#A practical integration sequence

1. Choose the SDK matching the application runtime.

2. Provision a persistent machine identity, or create an enrollment token for an ephemeral workload.

3. Grant the machine access only to the required projects and secrets.

4. Install the SDK and create one client for the selected vault_....

5. Read secrets by sk_... ID and keep values out of logs.

6. Add structured-field access or project-scoped export where it simplifies configuration.

7. Enable the encrypted fallback cache only when the workload has a defined stale-value policy.

8. Add watching when the application can safely reload rotated values at runtime.

9. Handle authentication, access, rate-limit, and configuration errors explicitly.

10. Review the machine’s grants and audit activity after deployment.

#Open-source SDKs

All official SikkerKey SDKs are fully open source under the MIT license. Source code, package metadata, examples, and issue trackers are available from SikkerKeyOfficial on GitHub.

Continue with the language-specific guide: Go, Python, Node.js, .NET, Kotlin, or PHP.