PNAUTHINFO3

Under this scheme, two authorization parameters must be passed along with the scheme.

• Credential parameter: Contains the userId of a MyPreferences user and the issued timestamp.
• Signature: Used to verify the identity of the requestor.

Both parameters are delimited by a space, as shown in the following example:

 
GET https://pm.mypreferences.com/Profiles/v4/SanchezAssociates/Programs HTTP/1.1
Host: pm.mypreferences.com
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:38.0) Gecko/20100101 Firefox/38.0
Accept: application/json
Accept-Language: null
Accept-Encoding: gzip, deflate
DNT: 1
Content-Type: application/json
Authorization: PNAUTHINFO3-HMAC-SHA256 Credential=RickSanchez/2015-08-10T20:11:00 Signature=Lbhe+fKoQPZhzUYWHMVADC4BhqtAMQkfAfpR6Wzbxe0=
Connection: keep-alive

Authorization Credential Parameter

This scheme defines two authorization parameters. The first is the credential parameter. It is composed of a UserId field and an issued timestamp field separated by a forward slash, as shown below:

Credential=(UserId)/(ISO 8601 Issued Timestamp)

UserId

The userId field must include a valid user id associated with an active MyPreferences client (account). In the example above, the UserId “RickSanchez” is an active, valid user for the client “SanchezAssociates”. 

ISO 8601 Issued Timestamp

The Issued Timestamp field must be a valid ISO 8601 formatted timestamp and cannot be a future date. This field is used to determine if the authorized request has expired. Future dates are considered invalid, and the request will be rejected by the API. 

By default, an authorized request will only be valid for 15 minutes from the issued date; however, this can be adjusted on a per client basis by setting the configuration value shown below. This is adjusted by contacting the MyPreferences support team. Please note that future schemes may migrate this field to another header.

Notes on time zones:

The MyPreferences API supports two time zones for the ISO 8601 issued timestamp. One is UTC, while the other is EST (UTC-5:00)/EDT (UTC-4:00). 

Authorization Signature Parameter

The second parameter is the Signature. The signature is a keyed or un-keyed message digest based on the crypto algorithm provided in the scheme. The format of the message also varies based on whether the scheme uses a keyed or un-keyed algorithm. Once the message digest is generated, it must be encoded using Base64 encoding scheme before being assigned to the Signature parameter, as shown below:

Signature=Base64Encoding(MessageDigest)

Keyed Algorithm

With the keyed algorithm, the message is composed of the ClientId field supplied from the URL and the UserId and ISO 8601 Issued Timestamp fields provided in the credential parameter.

Please note that future authorization schemes may use a different format and that these fields should NOT be URL encoded when composing the message. 

Each of these three fields must be concatenated together using a colon as a delimiter as shown below:

Message=(ClientId):(UserId):(ISO 8601 Issued Timestamp)

Once the message is generated, it is then hashed using the client’s private key and the crypto algorithm specified in the authorization scheme.

MessageDigest=HMAC-CryptoAlgorithm(Message, PrivateKey)

The signature, as shown in the example above, is generated as follows.

Signature=Base64Encoding(HMACSHA256(“SanchezAssociates:RickSanchez:2015-08-10T20:11:00”,“SeemslikearareopportunityMorty!”))

Additionally, the client’s private key is stored securely and can be rotated by sending a request to our support team.

Non-Keyed Algorithm

The non-keyed algorithm follows the same message format as the keyed algorithm, except it incorporates the private key into the message. This is to provide a small amount of additional security, yet it is still recommended to use the keyed algorithm whenever possible.

Message=(PrivateKey):(ClientId):(UserId):(ISO8601 Issued Timestamp):(PrivateKey)

As seen above, the private key is concatenated to the front and the back of the message before it is hashed. The message digest is generated based on the message and the crypto algorithm specified in the authorization scheme.

MessageDigest=CryptoAlgorithm(Message)

Additional Notes on Authorization Signature

Case Sensitivity

The signature is case sensitive to the fields supplied. When including a field like the ClientId in the URL or the UserId and Timestamp from the Credential parameter, it is vital to make sure that the value in those fields have the exact case syntax that was used when generating the signature. For example, if the ClientId that was used to generate the hash was SanchezAssociates, yet the URL has the case syntax of SANCHEZASSOCIATES, the authorization will fail and the request will be rejected.

Spaces and Special Characters in the UserId.

If the UserId field contains special characters or a space, it should be URL encoded before using it in the MessageDigest and as a Credential parameter.

Credential=URLEncode(UserId)/(ISO 8601 Issued Timestamp)

Message=(ClientId):(URLEncode(UserId)):(ISO 8601 Issued Timestamp)