User accounts

There are several types of user integration that Piano VX supports. The most important question to consider is where are my users' email addresses and passwords stored?

  • If you're using WordPress, most likely your users' data is stored in your local WordPress database.
  • If you are only using Janrain Engage or Gigya Social Login, your users' data could still be stored in your local database if the end result of logging in socially is creating a local account.

It's critical to understand exactly where your user records are being stored before beginning the process of a Piano integration.

Piano Accounts

If you are using Piano Accounts, all users being created during checkout are Piano accounts. You will have the same user administration and mining capabilities that you would if you were using any of our other integrations - the only difference is that users' email addresses and passwords are stored in Piano.

Users would go to to manage their accounts, update their subscriptions, change their passwords or other administrative functions.

From an integration perspective, the only configuration that you need is to tell our JavaScript code that you're using Piano Accounts.

tp.push(["setUseTinypassAccounts", true]);

There is no need to generate the UserRef or pass any user-specific data to us. Go here to learn the different ways that you can check access when using Piano Accounts.

Piano also uses OAuth to give you, via an iOS App, access to your VX resources.

Local Database / Custom Identity Management Service

If you are running a custom content management system, chances are that you have a local user database or custom identity management system setup that handles the process of user login and registration. With this type of integration, you need to generate the UserRef on all pages when the user is logged in.

Other important things to know about this type of integration:

  • You are responsible for new user registration and login on your website including any custom fields needed during registration
  • Piano does not store any user information other than email addresses, first and last names (optional)
  • You are responsible for maintaining a “my account” page where users can update and reset email addresses and passwords
  • Piano will provide the My Account Component for users to manage their subscriptions and credit cards
  • You are responsible for maintaining up-to-date SSL certificates to ensure communication between the browser and your website
  • There is no Piano-branded account created or any Piano branding during checkout
  • The checkout process happens within your website and there are no popups to Piano
  • Piano must be notified when a user's email address changes using /publisher/user/update to keep email notifications up-to-date
  • You will be able to create and update users programmatically via the API


If you are using WordPress, it is likely that your users are stored locally inside your WordPress database. In this case, you can either rely on the Piano VX WordPress plugin or you can generate the UserRef manually. Please contact us to receive the Piano VX WordPress plugin.


If you're using Drupal, it is likely that your users are stored locally inside of your Drupal database. In this case, you can rely on the Piano VX Drupal module or you can generate the UserRef manually. Contact us to receive the Piano VX Drupal module.

Janrain Capture

If you are using Janrain Capture, and not only Janrain Engage, then your user data is located in Janrain. Go here to read the full documentation on how to initialize Janrain within the Piano JavaScript.

If you are using Janrain Engage and not using Janrain Capture, then it is more likely that your users are located in your local database. If that is the case, you must generate the UserRef token for logged-in users to be able to complete checkout.

Generating the UserRef

Generating the UserRef is necessary if your users are stored in a local database or you are using a custom identity management provider. If you are using the Piano VX WordPress plugin, Janrain, or Piano Accounts, you don't need to generate the UserRef token.

The UserRef token should be generated on every page load for logged-in users and should not be stored in a cookie. The UserRef token is only valid for 10 minutes.

The data inside of the UserRef should be a json string, encrypted and base-64 encoded. Using Piano SDK for PHP, the UserRef string generation looks like this:

$userRef = TPUserRefBuilder::create( $userID, $userEmail )
                           ->setFirstName( $userFirstName )
                           ->setLastName( $userLastName )
                           ->setCreateDate( $userRegistrationDateTimestamp )
                           ->build( $pianoPrivateKey );

And to pass the UserRef value to Piano - use the following JavaScript:

tp = || [];
tp.push(["setUserRef", "<?php echo $userRef; ?>"]);


There are several fields that you must specify when generating the UserRef. The uid, email, and timestamp fields are all required. The create_date field is required only if you are creating registration terms and need to restrict the time window for when someone can register on your site and then gain access.

If no create_date is specified, we will use the Unix time from when the request comes in.


The uid field should be the globally unique, immutable user id local to your identity management system.

CMS Unique User UID
Wordpress $user→id
Drupal $user→uid
Joomla $user→id
RefineryCMS user_id

Note: The UID should be sent to Piano as a string, even if it an integer locally.


The email field should be the current email of the logged-in user.


The timestamp field should be an integer that represents the number of seconds since Unix epoch. This field is used to determine if the UserRef is expired or not. UserRef's should ideally be regenerated on every pageview, or at least every 10 minutes, since the UserRef times out after 10 minutes (we key off of the “timestamp” field to determine this).


The first_name field should be a string that represents the user's first name and is optional.


The last_name field should be a string that represents the user's last name and is optional.


The create_date field should be an integer that represents the date/time the user was created as the number of seconds since Unix epoch. If this field is not passed, we will use the current time when the user was created on the fly. This field is optional.

Testing the UserRef

Because in production, the UserRef is an encrypted token that can be hard to debug, there are a couple methods that Piano provides for you to test your UserRef implementation.

Open Encoding

In non-production environments you can set the UserRef using our open-encoding specification. This format is string that starts with {jox}, and is followed by a JSON object that contains the uid, email, and timestamp fields. If you are generating this in JavaScript, you can use the JSON.stringify method.

// this is the easier way to test in non-production; open encoding
tp.push(["setUserRef", "{jox}{\"uid\":\"test\",\"email\":\"\",\"timestamp\":1234567890}"]);

REST Endpoint

There is also a REST endpoint that you can use to test your integration.

curl \
	-d 'aid=YOURAID' \
	-d 'user_ref=aHR0cHM6Ly93d3cueW91dHViZS5jb20vd2F0Y2g/dj1kUXc0dzlXZ1hjUQ=='

This method will perform the following checks to ensure that the UserRef was created correctly:

  • Proper decryption using your app's private key
  • The JSON object has a valid email
  • The UserRef is not expired
  • The uid has a value