Download the PHP package sikkerkey/sdk without Composer

SikkerKey PHP SDK

Use the official SikkerKey PHP SDK to give a PHP application read access to the secrets its machine is authorized to use.

The SDK can:

• Read standard and structured secrets.
• List the secrets available to a machine.
• Export accessible secrets as application-friendly key/value pairs.
• Use persistent machine identities or memory-only ephemeral identities.
• Keep an optional encrypted fallback cache for temporary service or network outages.

After the client is initialized, every secret request is authenticated with the machine's Ed25519 identity. The SDK supports PHP 8.1 or newer and has no third-party Composer package dependencies.

Requirements

• PHP 8.1 or newer.
• The sodium, curl, and json PHP extensions.
• A SikkerKey vault and machine identity.
• The openssl extension when using the optional encrypted cache.

Install the SDK

Read your first secret

The SDK loads the machine identity from:

It signs the request with the machine's Ed25519 private key and returns the secret value as a string. Your application's access remains limited by the machine's configured access.

All SDK calls are synchronous.

Create a client

When no argument is supplied, the SDK checks SIKKERKEY_IDENTITY first. If that variable is not set, it uses the only registered vault under ~/.sikkerkey/vaults/.

If more than one vault is registered, select one explicitly. Missing identities, unreadable keys, invalid identity files, and ambiguous vault selection produce ConfigurationError.

The vault_ prefix is added when a vault ID is supplied without it.

Use a different identity directory

The SDK will look under:

Use an ephemeral identity

SikkerKey::bootstrapInMemory is designed for short-lived or read-only environments where an identity should not be stored on disk.

During bootstrap, the SDK:

1. Generates an Ed25519 key pair in memory.
2. Uses the enrollment token to register an ephemeral machine.
3. Keeps the private key inside the running PHP process.
4. Returns a client ready to read the secrets allowed by the token's access policy.

Nothing is written to disk. The private key disappears when the process exits.

The enrollment token registers the machine; it does not read secrets itself. The resulting machine remains subject to the token's permitted scope, use limit, hostname rules, and machine lifetime. Reads produce AuthenticationError after the machine expires.

Set the machine hostname and name

hostname defaults to the HOSTNAME environment variable and then to serverless. A name pattern configured on the enrollment token takes precedence over name.

For reliable ephemeral deployments:

• Set a machine lifetime long enough for the workload to finish.
• Allow enough token uses for expected cold starts and concurrency.
• Use a unique name pattern such as worker-{uuid8}.
• Ensure the vault's IP allowlist permits the workload's outbound address when an allowlist is enabled.

Each active ephemeral machine uses a machine slot until it expires.

Read secrets

Standard secrets

Structured secrets

getFields expects a JSON object. Scalar properties become strings; nested values are returned as JSON text. Another structure produces SecretStructureError.

Use getField when the application needs one field:

A missing field produces FieldNotFoundError with the available field names.

Discover accessible secrets

Limit the result to one project:

Each SecretListItem contains:

Listing returns metadata, not secret values.

Export secrets for application configuration

Limit the export to a project:

The returned array<string,string> uses uppercase environment-style names. Structured secrets are expanded into one entry per field:

You can apply the result to the current process:

Continue reads during temporary outages

The fallback cache is disabled by default:

After it is enabled, successful getSecret reads are stored under:

getFields and getField use getSecret, so their successful reads are cached too. Cache writes are best-effort and cannot turn a successful live read into a failure.

The SDK can return a cached value after a network failure, request timeout, or HTTP 502, 503, 504, 520 through 527, or 530.

Authentication failures, revoked access, missing secrets, rate limits, and other authoritative responses are never replaced by cached values.

Entries use AES-256-GCM with a key derived from the machine's Ed25519 identity and vault ID. Tampered entries and entries belonging to another identity are rejected. The .skc format is compatible with other SikkerKey SDKs and the SikkerKey CLI.

Limit cache age and observe fallback use

maxAge is measured in seconds. Passing null means no automatic expiry. The callback is optional; fallback is otherwise silent.

The cache is intended for a host with a persistent, protected identity directory, not a memory-only identity that disappears with the process.

Work with more than one vault

List locally registered vault IDs:

The returned list is sorted alphabetically.

Inspect the active machine

The identity values are available as read-only properties:

They are also available through methods:

Handle errors

Exception reference

Network failures and request timeouts use ApiError with httpStatus === 0.

Retries and timeout

Authenticated secret requests retry network failures and HTTP 429 or 503 responses up to three times. Retries wait 1, 2, and 4 seconds, and every attempt receives a fresh timestamp and nonce.

Connection and total request timeouts are each configured for 15 seconds. Other HTTP responses are returned immediately as their matching exception.

Feature-to-API reference

The PHP SDK does not run a background watcher. Applications that need change notifications can refresh values on their own schedule.

Runtime footprint

The SDK uses:

• ext-sodium for Ed25519 key generation and signing.
• ext-curl for HTTPS requests.
• ext-json for serialization.
• ext-openssl for the optional AES-GCM cache.

It has no third-party Composer package dependencies.

Documentation

• SikkerKey documentation
• SDK overview
• PHP SDK reference
• Machine authentication

License

The SikkerKey PHP SDK is available under the MIT License.