PHP SDK

The PHP SDK provides a client for integrating with Subnoto’s API. It handles Oak tunnel encryption, HTTP signature authentication, and includes a native PHP extension for AMD SEV-SNP attestation.

Installation

Download the latest release tarball from GitLab Packages and extract it into your project:

tar xzf subnoto-api-client-php-*.tar.gz -C vendor/subnoto

Add the PSR-4 autoload entry to your composer.json:

{
    "autoload": {
        "psr-4": {
            "Subnoto\\ApiClient\\": "vendor/subnoto/src/"
        }
    },
    "require": {
        "ext-oak_client_php": "*",
        "guzzlehttp/guzzle": "^7.0"
    }
}

Load the native extension by adding to your php.ini:

extension=/path/to/vendor/subnoto/ext/oak_client_php.so

Quick Start

Set your credentials as environment variables — SubnotoConfig picks them up automatically.

export SUBNOTO_ACCESS_KEY="your-access-key"
export SUBNOTO_SECRET_KEY="your-secret-key-hex"

<?php
require_once 'vendor/autoload.php';

use Subnoto\ApiClient\SubnotoClient;
use Subnoto\ApiClient\SubnotoConfig;

$config = new SubnotoConfig();
$client = new SubnotoClient($config);

// Check authentication
$whoami = $client->utils()->publicUtilsWhoamiPost();
echo "Authenticated as: " . $whoami->getTeamName() . "\n";

// List workspaces
$workspaces = $client->workspace()->publicWorkspaceListPost();
foreach ($workspaces as $ws) {
    echo "Workspace: " . $ws->getName() . "\n";
}

Creating an Envelope

use Subnoto\ApiClient\Model\PublicEnvelopeCreateFromFilePostRequest;

$request = new PublicEnvelopeCreateFromFilePostRequest([
    'workspace_id' => 'your-workspace-id',
    'name' => 'Contract for signing',
    'document' => fopen('/path/to/document.pdf', 'r'),
]);

$envelope = $client->envelope()->publicEnvelopeCreateFromFilePost(
    workspace_id: $request->getWorkspaceId(),
    name: $request->getName(),
    document: $request->getDocument(),
);

echo "Created envelope: " . $envelope->getId() . "\n";

Error Handling

use Subnoto\ApiClient\SubnotoError;

try {
    $result = $client->workspace()->publicWorkspaceGetPost(
        new \Subnoto\ApiClient\Model\PublicWorkspaceGetPostRequest([
            'workspace_id' => 'nonexistent-id',
        ])
    );
} catch (SubnotoError $e) {
    echo "API error ({$e->getStatusCode()}): {$e->getMessage()}\n";
}

API Sub-clients

The SubnotoClient provides typed sub-clients for each API group:

Sub-client	Access method	Description
Envelope	`$client->envelope()`	Create, send, sign envelopes and manage documents
Workspace	`$client->workspace()`	List and manage workspaces
Contact	`$client->contact()`	Create and manage contacts
Template	`$client->template()`	List templates
Logs	`$client->logs()`	View audit logs
Authentication	`$client->authentication()`	Create iframe tokens for embedded signing
Utils	`$client->utils()`	Utility endpoints (whoami)

Configuration

SubnotoConfig accepts the following parameters:

Parameter	Environment Variable	Description
`accessKey`	`SUBNOTO_ACCESS_KEY`	Your API access key
`secretKey`	`SUBNOTO_SECRET_KEY`	Your API secret key (hex-encoded)

$config = new SubnotoConfig(
    accessKey: 'your-access-key',
    secretKey: 'your-secret-key-hex',
);

Oak Tunnel Encryption

The PHP SDK uses the oak_client_php native extension to establish an encrypted tunnel with Subnoto’s AMD SEV-SNP enclaves. This ensures end-to-end encryption between your application and the enclave, with cryptographic attestation that the server is running in a genuine secure enclave.

The tunnel is established automatically when creating a SubnotoClient instance. Session management (including automatic retry on tunnel errors) is handled transparently.