README

⚠️ Alpha / pre-release. This SDK targets the real /v1/api/* API-key surface of api-velix-identity-core, defined in lib-velix-contracts/openapi/public-api.yaml (task #593). Only 6 endpoints exist today — anything else is not implemented.

Official PHP SDK for the VELIX Biometrics platform — facial access control B2B SaaS.

Requirements

• PHP 8.1+
• ext-json
• Composer

Installation

composer require velix/sdk

Auth

All requests are authenticated with an API key issued per tenant application. Send it via the x-api-key header (default) or Authorization: Bearer vlx_... (accepted by the same guard). Never use any other auth mechanism.

Quick Start

use Velix\VelixClient;
use Velix\Modules\CheckinModule;

$client = new VelixClient([
    'apiUrl'  => $_ENV['VELIX_API_URL'],
    'apiKey'  => $_ENV['VELIX_API_KEY'],
    'timeout' => 30, // seconds; default is 30s (30000ms) per SDK contract, always overridable
]);

$result = (new CheckinModule($client))->identify($frameBase64);
echo $result->matched ? 'MATCHED' : 'NOT MATCHED';

Environment Variables

Modules

Only the 6 real endpoints of /v1/api/* are implemented. PersonsModule, TenantsModule and WebhooksModule::configure() are kept for backward-compatible autoloading only — every method throws RuntimeException since no corresponding endpoint exists on the real API.

Velix Time is not covered. No /v1/api/time/* endpoint exists in the backend yet (see task #616) — there is no Time-related class in this SDK to call.

Onboarding Module

use Velix\Modules\OnboardingModule;

$onboarding = new OnboardingModule($client);

$result = $onboarding->enroll('João Silva', [$frame1, $frame2, $frame3], [
    'email' => 'joao@company.com',
    'external_id' => 'EMP-001',
]);

// $result->personId, $result->identityId, $result->enrolled, $result->framesProcessed

Checkin Module

use Velix\Modules\CheckinModule;

$checkin = new CheckinModule($client);

$result = $checkin->identify($frameBase64, [
    'topK' => 3,
    'location' => ['latitude' => -23.55, 'longitude' => -46.63],
]);

// $result->matched, $result->personId, $result->qualityScore, $result->message
// Liveness score is never exposed — only booleans/messages.

qr() and pin() throw RuntimeException — no such endpoint exists in /v1/api/*.

Me Module

use Velix\Modules\MeModule;

$me = (new MeModule($client))->get('person-uuid');
// $me->id, $me->name, $me->email, $me->phone, $me->photoUrl, $me->createdAt

LGPD Module

use Velix\Modules\LgpdModule;

$result = (new LgpdModule($client))->requestDeletion('person-uuid');
// $result->protocolNumber, $result->message

Events Module

use Velix\Modules\EventsModule;

$events = new EventsModule($client);

$guest = $events->createGuest('event-uuid', [
    'name' => 'Maria Souza',
    'email' => 'maria@example.com',
]);

$guest = $events->getGuest('event-uuid', $guest->id);

list(), get(), create(), configure(), delete() throw RuntimeException — no such event-management endpoints exist in /v1/api/*.

Webhook Signature Validation

WebhooksModule::validateSignature() is a pure local helper (no HTTP call) and remains functional. WebhooksModule::configure() throws RuntimeException — no matching endpoint.

use Velix\Modules\WebhooksModule;

$valid = WebhooksModule::validateSignature(
    payload:   file_get_contents('php://input'),
    signature: $_SERVER['HTTP_X_VELIX_SIGNATURE'],
    secret:    $_ENV['VELIX_WEBHOOK_SECRET']
);

if (!$valid) {
    http_response_code(401);
    exit;
}

Error Handling

use Velix\Exceptions\AuthException;
use Velix\Exceptions\BiometricException;
use Velix\Exceptions\VelixException;

try {
    $result = $checkin->identify($frameBase64);
} catch (AuthException $e) {
    echo 'Invalid API key';
} catch (BiometricException $e) {
    echo 'Face not recognized or liveness failed';
} catch (VelixException $e) {
    echo "HTTP {$e->getCode()}: {$e->getMessage()}";
}

Running Tests

composer install
composer exec phpunit

Local Development

composer install
composer exec phpunit -- --testdox

Get an API Key

Access the dashboard at velixbiometrics.com → Settings → API Keys → New Key.