Userplane provides our publishers the ability to add real-time engagement to their site as a service without having to host anything on their servers. As such our publishers often have need to proactively engage the Userplane service to make changes or react to the system based on their own business rules. Using the RESTful API allows our publishers to create a more seamless level of integration with their user experience by surfacing programmable interfaces to manage and control the data and experience on your implementation of Userplane.
Public and Private Keys
Userplane has two keys that are used in every API call as well as in the authorization process of users into the system. These two keys are categorized as a public key and a private key.Public Key
The public key is commonly referred to as the “siteID” ( or “domainCode” if your integration pre-dates the helix platform. ) and the private key is commonly referred to as the apiKey. These two keys serve two very different purposes but are equally important in the process of integration our REST API. The public key (siteID) is used to identify which of our publishers is placing the call to our servers, this key is exposed from time to time in spaces where end users may see the value.Private Key
The private key ( apiKey) is used to validate that the request was originated by someone, or more likely some server who has a copy of the private key. This key is meant to be completely hidden from the view of end users and should it ever become compromised you should generate a new api key as soon as you can.Regions
Currently we only have one region, but long term we expect the need to segment our infrastructure by region to provide the best possible performance for a geo-diverse user base. As a result you will always have a default “region” your implementation is assigned to. Currently the only value is “uswest”. This region should be used in place anytime you see “{region}” in the documentation. For example api.{region}.userplane.com would become api.uswest.userplane.com anywhere you see sample code or examples.Basic authentication
When placing any call to the REST API we require that you authenticate the request with a basic HTTP authentication credential. This is simply demonstrated via curl below:
curl https://{region}.api.userplane.com/v1/ping.json -v -u {siteId}:{apiKey}
This is the equivalent of your browser being prompted for a username and password when you try to access the resource, only when programming against our interface you will be coding the keys into your call so we can validate your call and authorize the action being taken.