TokenPassport Complex Type

A SOAP web services request that uses token-based authentication must use the TokenPassport complex type. By contrast, a request that authenticates in another way uses the SsoPassport type.

The TokenPassport references the TokenPassportSignature complex type, which is another important element in the token-based authentication process. Both complex types are defined in the Core XSD file.

For more details about these complex types, see the following sections:

• TokenPassport

• TokenPassportSignature

TokenPassport

The TokenPassport complex type uses the following fields. All are required:

Field	Description
account	Your NetSuite account ID. You can find this number at Setup > Integration > SOAP Web Services Preferences, in the Account ID field.
consumerKey	The consumer key for the integration record. This string was created when you checked the Token-based Authentication box on the integration record and saved it. This string is shown only one time, when it is first generated. If you no longer have this string, you can reset the credentials, as described in Regenerating a Consumer Key and Secret.
token	This is a string identifier or an ID of a token that represents a unique combination of a user, a role, and an integration record. This string can be generated in multiple ways. For details, see Manage TBA Tokens in the NetSuite UI.
nonce	This field should hold a unique, randomly generated alphanumeric string of 6–64 characters.
timestamp	This field should hold a current timestamp in Unix format.
signature	The signature is a hashed value. You create this value by using all of the other values in the TokenPassport, plus the appropriate token secret and consumer secret. Along with the signature itself, you must identify the algorithm used to create the signature. For details, see TokenPassportSignature.

Important:

To prevent issues due to out of sync time, keep time on your servers synchronized using Network Time Protocol (NTP).

TokenPassportSignature

You use the TokenPassportSignature complex type to identify the signature, which is a hashed value. The TokenPassportSignature also includes an attribute labeled algorithm, which you use to identify the algorithm used to create the signature.

At a high level, you create the signature by completing the following steps:

1. Create a base string. The base string is variable created from concatenating a series of values specific to the request. Use an ampersand as a delimiter between values. The values should be arranged in the following sequence:

   • NetSuite account ID

   • Consumer key

   • Token

   • Nonce (a unique, randomly generated alphanumeric string, with a minimum of six characters and maximum of 64)

   • Timestamp

   For example, suppose you have the following variables:

   • NetSuite account ID – 1234567

   • Consumer key – 71cc02b731f05895561ef0862d71553a3ac99498a947c3b7beaf4a1e4a29f7c4

   • Token – 89e08d9767c5ac85b374415725567d05b54ecf0960ad2470894a52f741020d82

   • Nonce – 6obMKq0tmY8ylVOdEkA1

   • Timestamp – 1439829974

   In this case, the base string would be as follows.

                 1234567&71cc02b731f05895561ef0862d71553a3ac99498a947c3b7beaf4a1e4a29f7c4&89e08d9767c5ac85b374415725567d05b54ecf0960ad2470894a52f741020d82&6obMKq0tmY8ylVOdEkA1&1439829974 
   
               

2. Create a key. The key is a string variable created by concatenating the appropriate consumer secret and token secret. These two strings should be conctatenated by using an ampersand.

   For example, suppose you have the following variables:

   • Consumer secret – 7278da58caf07f5c336301a601203d10a58e948efa280f0618e25fcee1ef2abd

   • Token secret – 060cd9ab3ffbbe1e3d3918e90165ffd37ab12acc76b4691046e2d29c7d7674c2

   In this case, the key would be as follows:

                 7278da58caf07f5c336301a601203d10a58e948efa280f0618e25fcee1ef2abd&060cd9ab3ffbbe1e3d3918e90165ffd37ab12acc76b4691046e2d29c7d7674c2 
   
               

3. Choose HMAC-SHA256 as the supported hash algorithm to create an RFC 2104-compliant signature.

4. Use the base string, the key, and the algorithm to create the signature. The signature must be encoded by Base64.

Note:

For an example of how to represent the signature and algorithm in a SOAP request, see Token-Based Authentication Details.

Related Topics

Requirements for Using Token-Based Authentication

Regenerating a Consumer Key and Secret

Updating a SOAP Web Services Integration to Send Token-Based Authentication Details

SOAP Web Services Governance for Token-Based Authentication

Token-Based Authentication Errors in SOAP Web Services

General Notices