How to use the PHP client library

Overview

The client library for PHP provides tools for easier integration with Piano. It can be used to perform server-side access checking, processing encrypted data, encrypting data, and making API requests.

Basic Usage

Configuration

The Piano library requires configuring connection credentials. First, create an instance of the configuration object:

// Include Tinypass - make sure to use the correct path
include_once "/path/to/api/TinypassClient.php";
$tinypassConfig = new TPConfig( $applicationId, $apiToken, $privateKey,
$isSandbox );

Parameters:

ApplicationId - 10 character application ID. This can be found on the Piano dashboard.
apiToken - 40 character API token. This can be found on the Piano dashboard.
privateKey - 40 character private key. This can be found on the Piano dashboard, or by making an API request.
isSandbox - To perform queries to sandbox.tinypass.com, set it to "True". To make queries to api.piano.io, set it to "False". To make queries to another dedicated environment listed here, set the value as a string URL to the API root.

Preparing to query

Before executing any queries, client objects should be initialized with the newly created configuration object.

$tinypassClient = new TinypassClient( $tinypassConfig );

Executing the query

All queries to the API can be executed through methods of the client object. The query can be executed using builder-pattern code.

// The resulting object of this operation will be an instance of
TPPublisherApp
$result = $tinypassClient
    ->PublisherApp()  // Get Publisher Application API
                ->getRequest()   // Create get application request
                ->aid( $applicationId ) // Set application id
                ->execute();   // Execute the query

The resulting object differs from which method was called. Refer to the documentation to see a complete list of the API methods and the data types they return.

Handling Errors

If the client encounters connection errors during execution, it will throw a standard expectation. The object that is returned will contain error information. If you are encountering API errors, you can handle them as follows:

// In case of error - the resulting object will contain "code"
attribute,
// which will be greater than 0, as well as "message" attribute,
containing error message.
if ( isset( $result->code ) && $result->code ) {
 throw new Exception( $result->message, $result->code );
}

Helper Classes

The Helper Class library provides several helper classes to make integrating with Piano easier.

UserRef token builder

Piano uses a special UserRef token to provide data about logged in users. This library provides a helper class for the generation of this token.

<?php
// Include Tinypass - make sure to use the correct path
include_once "/path/to/api/TinypassClient.php";
$userRef = TPUserRefBuilder::create( $userId, $userEmail ) // User id
and email are required parameters
   ->setFirstName( $userFirstName )    // Set user's first name
   ->setLastName( $userLastName )     // Set user's last name
   ->setCreateDate( $userRegistrationDate )  // Set user's registration
date (in seconds)
   ->set( $name, $value )
   ->build( $privateKey );
and return userRef token
?>
<script type="text/javascript">
// Set additional parameter
 // Encrypt the data using private key
 // Set userRef token for use in javascript library
 tp.push(["setUserRef", <?php echo json_encode( $userRef ) ?> ]);
</script>

For more information about this token, refer to the API documentation.

Webhook parser

For easier decryption and usage of webhooks, this library provides a webhook parser.

// Encrypted webhook data is provided as GET parameter
$encryptedData = strval( @$_GET['data'] );
// Decrypt and parse data
$webhookEvent = Webhook::parse( $encryptedData, $privateKey );
switch ($webhookEvent->getEventType()) {
 case TPEvent::ACCESS_EVENT:
  // Process as access event webhook
  break;
 case TPEvent::SUBSCRIPTION_EVENT:
  // Process as subscription event webhook
  break;
  case TPEvent::TEST_EVENT:
  // Process as test event webhook
break; }

For more information about webhooks, refer to the API documentation.

Access token parser

To minimize interaction with the API for access checking, Piano can store access information as a cookie. The library provides an access token parser to check access data from this cookie.

// Include Tinypass - make sure to use the correct path
include_once "/path/to/api/TinypassClient.php";
// Init configuration object. This can be omitted if configuration
object was initialised earlier.
$tinypassConfig = new TPConfig( $applicationId, $apiToken, $privateKey,
$isSandbox );
// Init Access token store object with created configuration
$tokenStore = new TPAccessTokenStore( $tinypassConfig );
// Parse cookies to get tokens
$tokenStore->loadTokensFromCookie( $_COOKIE );
// Get access token for some resource
$accessToken = $tokenStore->getAccessToken( $resourceId );
if ( $accessToken->isAccessGranted() ) {
 // Access is granted, content can be displayed
} else {
 // Access is denied, content should be hidden, and offer should be
displayed }

Last updated: June 23, 2026