Using Token Authentication

Use token-based authentication for a more secured experience. It expires after a short-period and cannot be reused. Use your BasicAuth credentials to obtain a token and use the token to send a request to the Spectrum OnDemand web service. It is an open format, JWT token, which allows you to validate that it was created by Spectrum OnDemand. You can also view the expiry time of the token.

Note: You can use either BasicAuth or token based authentication, based on your need. For system-to-system use cases, Basic Auth is recommended, while for browser or mobile application use cases, token based authentication should be preferred.

Note: SOAP is not supported.

Note: For information about HTTP status codes for token based authentication web services calls, see Token based authentication web services calls.

Obtaining the token

Get the token using REST/JSON GET call, providing your Spectrum OnDemand BasicAuth credentials.

Resource URL

https://TokenEndPoint/security/jwt?mins=Val

Authorization: Basic EncodedUsernameAndPassword

Request

Table 1. Parameters for input data
Parameters	Description
TokenEndPoint	One of the regional token end-points listed in theServer URLs.
mins	Specify the time (in minutes) after which the token will expire. Default is 5 mins. The minimum value is 1 min and the maximum is 10 minutes for Production and 60 minutes for Staging. If you specify a value larger than the maximum value, the maximum allowed value is used. For example, if you set 11 minutes for production, the token will expire after 10 minutes.

Example with JSON response

Request: This example requests a token with expiry set to 4 minutes.

https://token-amer.spectrum.precisely.com/security/jwt?mins=4

Host: token-amer.spectrum.precisely.com

Authorization: Basic U1BPRFVzZXJOYW1lOlNQT0RQYXNzd29yZA==

Response: Spectrum OnDemand returns a Status: 200 with a token in this REST format:

{ "access_token": "eyHJhbGciOiJSUzI1NiIsInR5cCI7IkpXVCJ9.eyqJqdGkiOiI1MzlmMGVhYjRiOGU1NzBlM2EzMzMzYmI0OGUwNDczZTJjM2EyYjljWQ2VkYjZjODlkZTFiOTEzZjk4OTI3YzhiNGViMGU2YTVhNGQyNmZhODU4ZjY5MWU0MjA1dsdfZTU4MjcxZDRjZGI4ZGM76yyY4ZTc5NjVlOWU3MTk5YWQ3NmYzOTllODU1MDNjMTNhOGMykNWY0ZDNlNjYkOWJhZDBiMmIxY2MxMDEwYzQ3ODE4OTdjMzY0YTczZjRkMjAxOGIiLCJpYXQiOjE2MDAxODg1MjIsImV4cCI7MTYwMDE4OTEyMn0.tm8uA_eXfNKxEGDPHMCUJKJwynpoQnwaA0F08z1WyY5ccwpthkhA_wI0Eg8tD0fRXv0HT3HjYD5bscxfsT6Ig-pBddBT7duLcyileRF3y9KDHlt2-f_FkCofIbnC4Hy4-zOsZyfUPoShhVRvZu9FV9GirGDltqv8az3lZTXrv3K0RqD352GlYEDOXV_1y9UzEVuSGghYyyZrb6YY8E8Uppu-0_qYY50n0doBgfNwZL1h5xL_ZiWpQFzKr3fBTpRHGGDLLkB335EHFtDyetOEDBNX65sodaQnnidcS6yKHOjmXcRW6EFLED2IK79hmhUiHaI56q-Qe_3_r-fZP_A2kRjw" }

If you receive a Status: 401, it either means that your BasicAuth credentials are not correct or that your Spectrum OnDemand account is not configured to use token based authentication. You can reach out to Precisely Support to enable token based authentication for your account.

Note: The token will only work on the type of environment it was created for. A token from Staging can only be used with Staging and a token from Production can be used for Production.

Accessing through browser, mobile

In your browser or mobile application, call the Spectrum OnDemand service via REST using TokenEndPoint and put the token obtained from the above step in the HTTP header as: Authorization: Bearer access_token.

Sample REST Request Using GET

This example illustrates how to make a REST request to the ValidateAddress service using the GET method with token URL:

https://token-amer.spectrum.precisely.com/rest/ValidateAddress/results.json?Data.
Country=usa&Data.AddressLine1=2 Blue Hill Plaza, Pearl River&Data.City=NY&Data.
StateProvince=NY&Data.PostalCode=10965

Host: token-amer.spectrum.precisely.com

Authorization:

Bearer eyHJhbGciOiJSUzI1NiIsInR5cCI7IkpXVCJ9.eyqJqdGkiOiI1MzlmMGVhYjRiOGU1NzBlM2EzMzMzYmI0OGUwNDczZTJjM2EyYjljWQ2VkYjZjODlkZTFiOTEzZjk4OTI3YzhiNGViMGU2YTVhNGQyNmZhODU4ZjY5MWU0MjA1dsdfZTU4MjcxZDRjZGI4ZGM76yyY4ZTc5NjVlOWU3MTk5YWQ3NmYzOTllODU1MDNjMTNhOGMykNWY0ZDNlNjYkOWJhZDBiMmIxY2MxMDEwYzQ3ODE4OTdjMzY0YTczZjRkMjAxOGIiLCJpYXQiOjE2MDAxODg1MjIsImV4cCI7MTYwMDE4OTEyMn0.tm8uA_eXfNKxEGDPHMCUJKJwynpoQnwaA0F08z1WyY5ccwpthkhA_wI0Eg8tD0fRXv0HT3HjYD5bscxfsT6Ig-pBddBT7duLcyileRF3y9KDHlt2-f_FkCofIbnC4Hy4-zOsZyfUPoShhVRvZu9FV9GirGDltqv8az3lZTXrv3K0RqD352GlYEDOXV_1y9UzEVuSGghYyyZrb6YY8E8Uppu-0_qYY50n0doBgfNwZL1h5xL_ZiWpQFzKr3fBTpRHGGDLLkB335EHFtDyetOEDBNX65sodaQnnidcS6yKHOjmXcRW6EFLED2IK79hmhUiHaI56q-Qe_3_r-fZP_A2kRjw

The JSON returned by this request is:

{"output_port": [
{ 
"ProcessedBy 
{ 
"output_port": [ 
{ 
"Confidence": "93", 
"RecordType": "HighRise",
"RecordType.Default": "Y", 
"CountryLevel": "A", 
"ProcessedBy": "USA", 
"MatchScore": "0", 
"AddressLine1": "2 Blue Hill Plz", 
"City": "Pearl River", 
"City.Result": "C", 
"StateProvince": "NY", 
"StateProvince.Result": "V", 
"PostalCode": "10965-3113", 
"PostalCode.Result": "V", 
"PostalCode.Base": "10965", 
"PostalCode.AddOn": "3113", 
"Country": "United States Of America", 
"AdditionalInputData": "Pearl River", 
"AdditionalInputData.Base": "", 
"AdditionalInputData.Unmatched": "PEARL RIVER", 
"HouseNumber": "2", 
"HouseNumber.Result": "V", 
"LeadingDirectional": "", 
"StreetName": "Blue Hill", 
"StreetName.Result": "C", 
"StreetName.PreferredAlias.Result": "", 
"StreetName.AbbreviatedAlias.Result": "", 
"StreetSuffix": "Plz", 
"StreetSuffix.Result": "S", 
"TrailingDirectional": "", 
"ApartmentLabel.Result": "R", 
"ApartmentNumber": "", 
"ApartmentNumber.Result": "R", 
"RRHC": "", 
"POBox": "", 
"PrivateMailbox": "", 
"HouseNumber.Input": "2", 
"StreetName.Input": "Blue Hill Plaza Pearl", 
"StreetSuffix.Input": "Riv", 
"City.Input": "NY", 
"StateProvince.Input": "NY", 
"PostalCode.Input": "10965", 
"Country.Input": "USA", 
"USBCCheckDigit": "3", 
"PostalBarCode": "99", 
"USCarrierRouteCode": "H095", 
"USFIPSCountyNumber": "087", 
"USCountyName": "Rockland", 
"USCongressionalDistrict": "17", 
"USLOTCode": "0001A", 
"USLOTSequence": "T9", 
"USLOTHex": "E8", 
"USAltAddr": "", 
"USLastLineNumber": "V15340", 
"USFinanceNumber": "356425", 
"USLACS": "N", 
"POBoxOnlyDeliveryZone": "", 
"RDI": "B", 
"ProbableCorrectness": "2", 
"user_fields": [] 
} 
] 
}

Token expiry

When the token expires, you will receive the HTTP 403 Unauthorized status code. You will then need to re-generate the token as explained in Obtaining the token section above.

You will also receive a 403 status when attempting to access a Spectrum OnDemand service that you do not have permission to access. So take care not to create an endless loop where you create a token and it fails on the first call to the service because you don't have access to it, create another token because you think it expired, and call the service which gives 403.

In case of expired or invalid token, the JSON returned will be:

{ 
'message': 'expired token'
}

Note: For more information about JSON Web Tokens, see https://jwt.io/introduction/.