Reference Guide

Introduction

The Token Server provides a critical layer of security for web applications that use services requiring a license key. When you integrate a service directly into a public-facing website, there’s a significant risk of exposing your license key within the site’s code. If a malicious actor finds this key, they could potentially use your licensed services without authorization, leading to security breaches or unexpected costs.

To solve this problem, the Token Server acts as a secure intermediary. Instead of placing your main license key in the public code, your private server-side application makes a request to the Token Server. In return, it receives a secure, temporary token with a limited lifespan. This disposable token can then be safely passed to the public website for its use, ensuring that your license key is never exposed.

The Token Server can:

• Generate secure, temporary authentication tokens for client-side use.

• Conceal your license key to prevent it from being exposed in public-facing code.

• Enhance web application security by providing a safer method for authentication.

• Control the active lifespan of a token, from a minimum of 1 minute up to 99 hours.

CORS Handling - Header Changes

The Access-Control response headers for some requests will change by December 2025.

To read more about this change, please see the advisory.

Using the Token Server

The token server is most often used when your license string must be concealed, such as in a web page using Express Entry that is facing the public.

Tokens are more secure when compared to the other methods of passing sensitive information in plain text over a network, where it could be observed by a third party. PHP code and a JavaScript script which calls the PHP are provided to demonstrate how to implement tokens in a web page.

In order to implement the PHP and JavaScript sample:

• The server must have PHP enabled.

• The sample PHP must be loaded on the server and your License Key must be entered where marked in the code.

• The JavaScript sample must be pasted into your webpage and edited with your IP information.

• Both the PHP sample and the calling Javascript must be on the same domain.

Note

Note that the page where the JavaScript resides must be in the same domain as the file containing the PHP token-handling code. This is due to ‘same origin policy’ of AJAX. If Express Entry does not respond with addresses after inserting/adding the Javascript and PHP code, make sure that the JavaScript is called from the same domain as the server hosting the PHP, and that the token variable is being used instead of your ident or License Key.

The code is commented where the necessary changes (such as adding the License Key) are to be made.

Base URL

https://tokenservice.melissadata.net

New to Melissa Cloud APIs?

We highly recommend first time users of our Cloud APIs to review our Using Melissa Cloud APIs section. It will cover critical topics like:

• Licensing

• Rate Limiting

• Datacenter and IP Information

• Protocols and Usage

Endpoints

/v3/web/Service.svc/RequestToken

Through the Token Server you can request a token for use with your Melissa product.

Try It Now

Note

Make sure to replace {{customerId}} with your license key.

Get it here!

• GET JSON

curl -X GET "https://tokenservice.melissadata.net/v3/JSON/Service.svc/RequestToken?\
&L={{customerId}}\
&P=GlobalExpressEntry\
&IP=\
&TS=0015" \
-H "Content-Type: application/json" \
-H "Accept: application/json"

Request Parameters

Code	Description
IP	Optional. This is added security. If you send the client IP Address in your public-facing web page setup, we can detect unauthorized use of your tokens and take preventative measures.
L	Required. The License Key issued by Melissa.
P	Required. Specifies which package(s) the token should be generated for. See Packages for more information. Default is all packages.
TS	Optional. The token timespan in the format HHMM. The minimum lifespan is 1 minute (0001), with the maximum being 99 hours (9900). Default is 5 minutes.

Packages

Specifying which package(s) to generate a token for.

Delimit multiple packages with a ,.

Product	Package Name
BusinessCoder	BusinessCoder BusinessCoder-Contacts
CiceroAPI	CiceroAPI CiceroAPI-Region
Contribution	Contribution-Contribution
DataRetriever	DataRetriever-Business DataRetriever-Consumer DataRetriever-ConsumerTwo DataRetriever-MAK DataRetriever-NewHomeowners DataRetriever-NewMovers
Druginator	Druginator
GlobalAddressVerification	GlobalAddressVerification GlobalAddressVerification-GeoCode
GlobalEmail	GlobalEmail GlobalEmail-Premium
GlobalExpressEntry	GlobalExpressEntry GlobalExpressEntry-GeoCode
GlobalIP	GlobalIP
GlobalName	GlobalName
GlobalPhone	GlobalPhone GlobalPhone-CallerID GlobalPhone-GlobalPremium GlobalPhone-NAPremium
IPToConsumer	IPToConsumer
LeadGen	LeadGen-Business LeadGen-GlobalAddressDatabase
PeopleBusinessSearch	PeopleBusinessSearch
PersonatorConsumer	PersonatorConsumer PersonatorConsumer-Append PersonatorConsumer-Demographics PersonatorConsumer-GeoCode PersonatorConsumer-GeoPoint PersonatorConsumer-Move PersonatorConsumer-Verify
PersonatorIdentity	PersonatorIdentity PersonatorIdentity-Verify PersonatorIdentity-Watchlist
PersonatorSearch	PersonatorSearch
Property	Property Property-Shapes
ReverseGeoCoder	ReverseGeoCoder ReverseGeoCoder-Geocoder
SmartMover	SmartMover-Canada SmartMover-UnitedStates
SSNNameMatch	SSNNameMatch
StreetRoute	StreetRoute
Vault	Vault
WebSmart	WebSmart-AddressCheck WebSmart-DeliveryIndicator WebSmart-DPV WebSmart-Email WebSmart-Geocode WebSmart-GeoPoint WebSmart-MultipleRecords WebSmart-Name WebSmart-Phone WebSmart-StreetData WebSmart-ZipSearch

Headers

• GET JSON

Content-Type: application/json
Accept: application/json

Response

• GET JSON

{
  "Result": "",
  "Token": "{{computedToken}}"
}

Response Fields

Output Name	Description
RequestTokenResponse	This contains the requested token and any result codes.
Result	Contains result codes indicating any errors with the request.
Token	This contains the requested token to be used.

Sample Project

• https://download.melissadata.com/SampleCodes/Current/DQWS3/ExpressEntry/TokenIP2.zip

Sample Code

PHP Code

<?php
  // change this to your License Key
  $License = '########';

  //APACHE - You can use any other ways to get your external IP. Make sure that its echoing external IP not internal LAN IP.
  //Depending on how secure or optimized you want to capture your IP address. You may want to change how IP is determined
  //EXAMPLE ONLY
  //$host= gethostname();
  //$ip = gethostbyname($host);

  //IIS
  //EXAMPLE ONLY
  $ip = gethostbyname($_SERVER['SERVER_NAME']);
  //check for function
  if ( !isset($_REQUEST['function']) )
    exit();
  else
    $func = $_REQUEST['function'];
    //get the token
      if ($func == 'gettoken')
      {
        //customize the token request
        //example for Check Action
        $xml = file_get_contents('https://tokenservice.melissadata.net/v3/JSON/Service.svc/RequestToken?L=' . $License . '&P=pkgExpressEntry&IP=' . $ip);
        //unpack the xml
        $xml_r = new SimpleXMLElement($xml);
        //grab out the token
        $token = (string)$xml_r->Token;

        //send the token to the client in a json packet
        $data[] = array('token' => $token);
        //this encodes the data and sends it back to the client
        echo json_encode($data);
        flush();
      }
?>

JavaScript Code (for your web page)

var token;
window.onload = function()
{
  $.ajax(
  {
    type: "POST",
    // Your PHP server hostname or IP in the following line
    url: "http://192.168.13.237/licensekey.php", //NOTE:  ajax requires that the client and server side scripts be located on the same domain
    data: {function:"gettoken"},
    dataType: 'json',
    success: function(data)
    {
      token = data[0].token;
      //alert(token); // uncomment this if you want to see the token being returned
    }
  });
}

Result Codes

Please visit Token Server Result Codes for the full list of result codes returned by the Token Server.