paspoid/server-api-php

Official PHP SDK for paspo.id Server API - Seamless SSO transaction management and identity verification for PHP backends

dev-main 2026-07-30 08:28 UTC

Requires

• php: >=8.1
• ext-curl: *
• ext-json: *

Requires (Dev)

• phpunit/phpunit: ^10.0 || ^11.0

MIT

• Daniyar Kalmanbetov

Published on Packagist.org on 2026-07-30 08:28 UTC

README

Official PHP SDK for integrating backends with the paspo.id Server API (Transaction and Authentication Service).

📋 Overview

The Paspo ID Server API PHP SDK allows PHP applications (Laravel, Symfony, WordPress, custom backends) to initiate authentication transactions, issue temporary transaction keys, and validate nonces with the Paspo ID identity provider.

• Clean Architecture design matching Java, Kotlin, and JavaScript SDKs.
• Zero Heavy External Dependencies: Built using PHP 8.1+ native cURL and JSON extensions.
• Strict Type Safety: Fully typed with PHP 8.1 readonly properties, named arguments, and strict return types.
• Composer PSR-4 Compliant for seamless autoloading (Paspoid\).

⚙️ Requirements

• PHP: 8.1 or higher
• Extensions: ext-curl, ext-json

📦 Installation

Install the package via Composer:

composer require paspoid/paspoid

🚀 Quick Start

<?php

require_once __DIR__ . '/vendor/autoload.php';

use Paspoid\Client;
use Paspoid\Lib\Domain\Anomaly\PaspoidException;

$client = new Client(
    baseUrl: 'https://paspo.id',
    apiKey: 'YOUR_API_KEY',
    apiSecret: 'YOUR_API_SECRET'
);

try {
    // 1. Obtain a temporary transaction key
    $keyResponse = $client->getKey(
        servicePublicId: 'YOUR_SERVICE_PUBLIC_ID',
        transactionType: 'phones'
    );
    echo "Key: {$keyResponse->key}\n";
    echo "Validation Window: {$keyResponse->validationWindow}\n";

    // 2. Validate transaction status using the nonce/key
    $valResponse = $client->validate($keyResponse->key);
    echo "Status: {$valResponse->status}\n";
    echo "Data Type: " . ($valResponse->dataType ?? 'null') . "\n";
    echo "Data Value: " . ($valResponse->dataValue ?? 'null') . "\n";
} catch (PaspoidException $e) {
    echo "Paspo SDK Error: " . $e->getMessage() . "\n";
} finally {
    $client->close();
}

🔄 Integration Flow

sequenceDiagram
    autonumber

    actor Backend as PHP Backend (Laravel / Symfony)
    participant SDK as paspo.id PHP SDK
    participant API as paspo.id Server API

    Note over Backend,API: Secure Server-to-Server Communication

    Backend->>SDK: new Client(baseUrl, apiKey, apiSecret)
    Backend->>SDK: getKey(servicePublicId, transactionType)
    SDK->>API: POST /v1/ext/get-key
    API-->>SDK: key + validation_window
    SDK-->>Backend: GetKeyResponse

    Note over Backend: User completes SSO consent flow

    Backend->>SDK: validate(nonce)
    SDK->>API: POST /v1/ext/validate
    API-->>SDK: status + verified user profile data
    SDK-->>Backend: ValidateResponse

Loading

🛠 API Reference

Paspoid\Client

public function __construct(
    string $baseUrl,
    string $apiKey,
    string $apiSecret,
    int $timeoutSeconds = 15
)

Methods

Method	Parameters	Returns	Description
getKey	string $servicePublicId, string $transactionType	GetKeyResponse	Requests a new transaction key
validate	string $nonce	ValidateResponse	Validates transaction status by nonce
close	void	void	Releases client resources

Data Models

Paspoid\Responses\GetKeyResponse

• public readonly string $key: The one-time transaction key.
• public readonly string $validationWindow: Expiration / validation window of the key.

Paspoid\Responses\ValidateResponse

• public readonly string $status: Transaction validation status.
• public readonly ?string $dataType: Type of profile data returned (e.g. phone, email).
• public readonly ?string $dataValue: Verified profile data value.
• public readonly ?array $phoneData: Detailed phone data (if available).
• public readonly ?array $deviceData: Device metadata (if available).

🚨 Error Handling

All SDK exceptions inherit from Paspoid\Lib\Domain\Anomaly\PaspoidException:

• ConfigurationException: Thrown when client configuration is invalid (e.g. empty apiKey or malformed baseUrl).
• RequestValidationException: Thrown when required method parameters are empty.
• TransportException: Network connectivity failures or cURL timeouts.
• ApiException: Server returned an HTTP error status (4xx / 5xx). Access details via $e->statusCode, $e->responseBody, and $e->endpoint.
• DecodeException: Response JSON parsing or structural validation failures.

📄 License

Distributed under the MIT License. See LICENSE for details.