README

The Tripwire PHP library provides convenient access to the Tripwire API from applications written in PHP. It includes a framework-agnostic client for Sessions, visitor fingerprints, Organizations, Organization API key management, sealed token verification, Gate, and Gate delivery/webhook helpers.

The library also provides:

• a fast configuration path using TRIPWIRE_SECRET_KEY
• a bundled PSR-18 transport stack with support for custom PSR clients and factories
• structured API errors and built-in sealed token verification
• webhook endpoint management, test sends, and event delivery history
• public, bearer-token, and secret-key auth modes for Gate flows
• Gate delivery/webhook helpers

Documentation

See the Tripwire docs and API reference.

Installation

You don't need this source code unless you want to modify the package. If you just want to use the package, run:

composer require abxy/tripwire-server

Requirements

• PHP 8.1+

Usage

Use TRIPWIRE_SECRET_KEY or secretKey for core detect APIs. For public or bearer-auth Gate flows, the client can also be created without a secret key:

<?php

use Tripwire\Server\Client;

$client = new Client(secretKey: getenv('TRIPWIRE_SECRET_KEY') ?: null);

$page = $client->sessions()->list(verdict: 'bot', limit: 25);
$session = $client->sessions()->get('sid_0123456789abcdefghjkmnpqrs');

echo $session->decision['automation_status'] . ' ' . ($session->highlights[0]['summary'] ?? '') . PHP_EOL;

Sealed token verification

<?php

use Tripwire\Server\SealedToken;

$result = SealedToken::safeVerify($sealedToken, getenv('TRIPWIRE_SECRET_KEY') ?: null);

if (!$result->ok) {
    error_log($result->error?->getMessage() ?? 'Tripwire verification failed.');
    return;
}

echo $result->data?->decision['verdict'] . ' ' . $result->data?->decision['risk_score'];

Pagination

<?php

foreach ($client->sessions()->iterate(search: 'signup') as $session) {
    echo $session->id . ' ' . $session->latest_decision['verdict'] . PHP_EOL;
}

Visitor fingerprints

<?php

$fingerprint = $client->fingerprints()->get('vid_0123456789abcdefghjkmnpqrs');
echo $fingerprint->id;

Organizations

<?php

$organization = $client->organizations()->get('org_0123456789abcdefghjkmnpqrs');
$updated = $client->organizations()->update('org_0123456789abcdefghjkmnpqrs', name: 'New Name');

echo $updated->name;

Organization API keys

<?php

$created = $client->organizations()->apiKeys()->create('org_0123456789abcdefghjkmnpqrs', name: 'Production', type: 'secret', environment: 'live');
$client->organizations()->apiKeys()->revoke('org_0123456789abcdefghjkmnpqrs', $created->id);

Webhooks

<?php

$endpoint = $client->webhooks()->createEndpoint(
    'org_0123456789abcdefghjkmnpqrs',
    'Production alerts',
    'https://example.com/tripwire/webhook',
    ['session.result.persisted', 'gate.session.approved'],
);

$events = $client->webhooks()->listEvents(
    'org_0123456789abcdefghjkmnpqrs',
    endpointId: $endpoint->id,
    type: 'session.result.persisted',
);

echo $events->items[0]->webhook_deliveries[0]->status;

Gate APIs

<?php

use Tripwire\Server\Client;
use Tripwire\Server\GateDelivery;

$client = new Client();
$services = $client->gate()->registry()->list();
$session = $client->gate()->sessions()->create(
    serviceId: 'tripwire',
    accountName: 'my-project',
    delivery: GateDelivery::createDeliveryKeyPair()['delivery'],
);

echo $services[0]->id . ' ' . $session->consent_url . PHP_EOL;

Gate delivery and webhook helpers

<?php

use Tripwire\Server\GateDelivery;

$keyPair = GateDelivery::createDeliveryKeyPair();
$response = GateDelivery::createGateApprovedWebhookResponse([
    'delivery' => $keyPair['delivery'],
    'outputs' => [
        'TRIPWIRE_PUBLISHABLE_KEY' => 'pk_live_...',
        'TRIPWIRE_SECRET_KEY' => 'sk_live_...',
    ],
]);
$payload = GateDelivery::decryptGateDeliveryEnvelope($keyPair['private_key'], $response['encrypted_delivery']);

echo $payload['outputs']['TRIPWIRE_SECRET_KEY'] . PHP_EOL;

Error handling

<?php

use Tripwire\Server\Exception\TripwireApiError;

try {
    $client->sessions()->list(limit: 999);
} catch (TripwireApiError $error) {
    error_log($error->status . ' ' . $error->code . ' ' . $error->getMessage());
}

Support

If you need help integrating Tripwire, start with tripwirejs.com/docs.