PHPackages                             sikkerkey/sdk - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Security](/categories/security)
4. /
5. sikkerkey/sdk

ActiveLibrary[Security](/categories/security)

sikkerkey/sdk
=============

SikkerKey PHP SDK — read secrets with Ed25519 machine authentication

v1.0.1(1mo ago)03↓88.9%MITPHPPHP >=8.1

Since Jun 1Pushed 1mo agoCompare

[ Source](https://github.com/SikkerKeyOfficial/sikkerkey-php)[ Packagist](https://packagist.org/packages/sikkerkey/sdk)[ Docs](https://sikkerkey.com)[ RSS](/packages/sikkerkey-sdk/feed)WikiDiscussions master Synced 1w ago

READMEChangelogDependenciesVersions (3)Used By (0)

SikkerKey PHP SDK
=================

[](#sikkerkey-php-sdk)

[![License: MIT](https://camo.githubusercontent.com/784362b26e4b3546254f1893e778ba64616e362bd6ac791991d2c9e880a3a64e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d677265656e2e737667)](LICENSE)[![Packagist](https://camo.githubusercontent.com/9219675135274a8f207c1fc0609e8818d36590ab15e6fda813390b9d7a93eb64/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f73696b6b65726b65792f73646b)](https://packagist.org/packages/sikkerkey/sdk)[![PHP](https://camo.githubusercontent.com/1f28f2b4faa0e0f1224d8870dbbc65deeea67e3391cd0be5ca39bb23feddf1cc/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e312b2d3737374242343f6c6f676f3d706870266c6f676f436f6c6f723d7768697465)](https://www.php.net)

The official PHP SDK for [SikkerKey](https://sikkerkey.com). Read-only access to secrets using Ed25519 machine authentication. No external Composer dependencies, uses the bundled `sodium` and `curl` extensions. Runs on persistent hosts (identity on disk) and serverless or ephemeral environments (in-memory bootstrap).

Installation
------------

[](#installation)

```
composer require sikkerkey/sdk
```

Requires PHP 8.1+ with the `sodium` and `curl` extensions (both bundled with modern PHP).

Quick Start
-----------

[](#quick-start)

```
use SikkerKey\SikkerKey;

$sk = SikkerKey::create('vault_abc123');
$apiKey = $sk->getSecret('sk_stripe_key');
```

The SDK reads the machine identity from `~/.sikkerkey/vaults//identity.json`, signs every request with the machine's Ed25519 private key, and returns the decrypted value.

Client Creation
---------------

[](#client-creation)

```
// Explicit vault ID
$sk = SikkerKey::create('vault_abc123');

// Direct path to identity file
$sk = SikkerKey::create('/etc/sikkerkey/vaults/vault_abc123/identity.json');

// Auto-detect from SIKKERKEY_IDENTITY env or single vault on disk
$sk = SikkerKey::create();
```

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

Serverless (In-Memory Bootstrap)
--------------------------------

[](#serverless-in-memory-bootstrap)

On a long-lived host the SDK loads a persistent identity from disk. Serverless and other ephemeral or read-only-filesystem environments (AWS Lambda, Google Cloud Run, Fly.io, and similar) have no identity to persist. `SikkerKey::bootstrapInMemory()` handles that case: it generates an Ed25519 keypair in memory, registers an ephemeral machine with an enrollment token, and returns a ready client. Nothing is written to disk.

```
use SikkerKey\SikkerKey;

$sk = SikkerKey::bootstrapInMemory(
    getenv('SIKKERKEY_VAULT_ID'),
    getenv('SIKKERKEY_ENROLLMENT_TOKEN'),
);

$dbUrl = $sk->getSecret('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.

Enrollment happens once, in the `bootstrapInMemory` call. The returned client then behaves exactly like one created from disk: it signs each read with the in-memory key. The private key is gone when the process exits. The ephemeral machine lives for the lifetime set on the token; reading after it expires throws `AuthenticationError`, so size the token's machine lifetime to your workload. The common path is to read secrets at startup and hold the values.

### Options

[](#options)

```
$sk = SikkerKey::bootstrapInMemory(
    $vaultId,
    $token,
    hostname: 'worker-1',   // defaults to $HOSTNAME, then "serverless"
    name: 'batch-runner',   // overridden if the token defines a name pattern
);
```

### Provisioning the Token

[](#provisioning-the-token)

When you create the enrollment token for a serverless or ephemeral 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.
- Set a name pattern on the token (for example `worker-{uuid8}`) so each machine gets a unique name. A name pattern takes precedence over `name`.

Each live ephemeral machine counts against your plan's machine limit until it expires.

Reading Secrets
---------------

[](#reading-secrets)

### Single Value

[](#single-value)

```
$apiKey = $sk->getSecret('sk_stripe_prod');
```

### Structured (Multiple Fields)

[](#structured-multiple-fields)

```
$fields = $sk->getFields('sk_db_prod');
$host = $fields['host'];       // "db.example.com"
$password = $fields['password']; // "hunter2"
```

Throws `SecretStructureError` if the secret value is not a JSON object.

### Single Field

[](#single-field)

```
$password = $sk->getField('sk_db_prod', 'password');
```

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

Listing Secrets
---------------

[](#listing-secrets)

```
// All secrets this machine can access
foreach ($sk->listSecrets() as $s) {
    echo "{$s->id}: {$s->name}\n";
}

// Secrets in a specific project
$projectSecrets = $sk->listSecretsByProject('proj_production');
```

Returns `SecretListItem[]` with `id`, `name`, `fieldNames` (nullable), and `projectId` (nullable).

Export
------

[](#export)

```
// All secrets as a flat associative array
$env = $sk->export();
// ["API_KEY" => "sk-live-...", "DB_CREDS_HOST" => "db.example.com", "DB_CREDS_PASSWORD" => "s3cret"]

// Scoped to a project
$env = $sk->export('proj_production');

// Inject into the environment
foreach ($sk->export() as $key => $value) {
    putenv("{$key}={$value}");
}
```

Structured secrets are flattened: `SECRET_NAME_FIELD_NAME`.

Multi-Vault
-----------

[](#multi-vault)

```
$prod = SikkerKey::create('vault_a1b2c3');
$staging = SikkerKey::create('vault_x9y8z7');

$prodKey = $prod->getSecret('sk_api_key');
$stagingKey = $staging->getSecret('sk_api_key');
```

### List Registered Vaults

[](#list-registered-vaults)

```
$vaults = SikkerKey::listVaults();
// ["vault_a1b2c3", "vault_x9y8z7"]
```

Static method.

Machine Info
------------

[](#machine-info)

```
$sk->machineId;    // "550e8400-e29b-41d4-a716-446655440000"
$sk->machineName;  // "api-server-1"
$sk->vaultId;      // "vault_abc123"
$sk->apiUrl;       // "https://api.sikkerkey.com"
```

Read-only properties (also available as `machineId()`, `machineName()`, `vaultId()`, `apiUrl()` methods).

Error Handling
--------------

[](#error-handling)

```
use SikkerKey\NotFoundError;
use SikkerKey\AccessDeniedError;
use SikkerKey\AuthenticationError;
use SikkerKey\ApiError;

try {
    $secret = $sk->getSecret('sk_nonexistent');
} catch (NotFoundError) {
    // 404 - secret doesn't exist
} catch (AccessDeniedError) {
    // 403 - machine not approved or no grant
} catch (AuthenticationError) {
    // 401 - invalid signature or unknown machine
} catch (ApiError $e) {
    // any other HTTP error
    echo $e->httpStatus;
}
```

### Exception Hierarchy

[](#exception-hierarchy)

```
SikkerKeyError (extends Exception)
├── ConfigurationError      - identity/key issues
├── SecretStructureError    - secret is not a JSON object (getFields)
├── FieldNotFoundError      - field not in structured secret (getField)
└── ApiError                - HTTP error (has $httpStatus property)
    ├── AuthenticationError - 401
    ├── AccessDeniedError   - 403
    ├── NotFoundError       - 404
    ├── ConflictError       - 409
    ├── RateLimitedError    - 429
    └── ServerSealedError   - 503

```

Identity Resolution
-------------------

[](#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 the base directory with `SIKKERKEY_HOME`.

Environment Variables
---------------------

[](#environment-variables)

VariableDescription`SIKKERKEY_IDENTITY`Path to `identity.json` - overrides vault lookup`SIKKERKEY_HOME`Base config directory (default: `~/.sikkerkey`)Method Reference
----------------

[](#method-reference)

MethodReturnsDescription`SikkerKey::create(vaultOrPath?)``SikkerKey`Create client from disk identity (static)`SikkerKey::bootstrapInMemory(vaultId, token, hostname?, name?)``SikkerKey`Memory-only serverless bootstrap (static)`SikkerKey::listVaults()``string[]`List registered vault IDs (static)`getSecret(secretId)``string`Read a secret value`getFields(secretId)``array`Read structured secret`getField(secretId, field)``string`Read single field`listSecrets()``SecretListItem[]`List all accessible secrets`listSecretsByProject(projectId)``SecretListItem[]`List secrets in a project`export(projectId?)``array`Export as env mapAuthentication
--------------

[](#authentication)

Every request includes Ed25519-signed headers:

- `X-Machine-Id` — machine UUID
- `X-Timestamp` — Unix timestamp
- `X-Nonce` — random base64 nonce (replay protection)
- `X-Signature` — signature of `method:path:timestamp:nonce:bodyHash`

HTTPS is enforced for all non-localhost connections. 15-second request timeout. 429 and 503 responses are retried up to 3 times with exponential backoff (1s, 2s, 4s).

Dependencies
------------

[](#dependencies)

None at the Composer level. Uses the bundled `ext-sodium` (Ed25519 keygen and signing) and `ext-curl` (HTTP). Requires PHP 8.1+.

License
-------

[](#license)

MIT - see [LICENSE](LICENSE) for details.

###  Health Score

37

—

LowBetter than 81% of packages

Maintenance90

Actively maintained with recent releases

Popularity3

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity43

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~5 days

Total

2

Last Release

48d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/271139548?v=4)[SikkerKey](/maintainers/sikkerkey)[@SikkerKey](https://github.com/SikkerKey)

---

Top Contributors

[![SikkerKeyOfficial](https://avatars.githubusercontent.com/u/274411411?v=4)](https://github.com/SikkerKeyOfficial "SikkerKeyOfficial (4 commits)")

---

Tags

phpphp-librarysecrets-managementsecrets-managerEd25519vaultsecretssecrets-managersikkerkey

### Embed Badge

![Health badge](/badges/sikkerkey-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/sikkerkey-sdk/health.svg)](https://phpackages.com/packages/sikkerkey-sdk)
```

###  Alternatives

[paragonie/certainty

Up-to-date, verifiable repository for Certificate Authorities

2662.6M22](/packages/paragonie-certainty)[simplito/elliptic-php

Fast elliptic curve cryptography

2302.4M275](/packages/simplito-elliptic-php)[captainhook/secrets

Utility classes to detect secrets

114.4M1](/packages/captainhook-secrets)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)