All MyPreferences 3.0 Version 4 API users can securely access and interact with MyPreferences APIs using two different authorization methods: OAuth (client-credentials) and Custom Authorization Scheme.

OAuth (Client-Credentials)

OAuth is a widely adopted industry-standard protocol that enables secure and controlled access to resources. With OAuth (client-credentials) authorization, your application can access MyPreferences API without the need to share sensitive credentials.

To get started with OAuth 2.0 (client-credentials) authorization, visit the OAuth section.

Custom Authorization Scheme

In addition to OAuth, we offer a custom authorization scheme that caters to specific use cases and security requirements. Our custom authorization scheme offers advanced access control to resources, providing an alternative authorization method for clients that may not be equipped to implement OAuth. With this custom approach, clients can securely interact with our API and leverage its robust authorization capabilities.

For comprehensive details on using our custom authorization scheme, please refer to the Custom Auth Scheme section.

MyPreferences APIs support the OAuth 2.0 Client Credentials Flow for authentication and authorization. In this flow, the client application exchanges its client credentials which includes their MyPreferences Client ID and Client Secret for an access token.

OAuth Flow

1. Send client credentials to the MyPreferences OAuth Token API via a POST request.
2. The OAuth Token API validates the client credentials and returns an access token.
3. You can now use the access token to access MyPreferences REST API.
4. The MyPreferences REST API will grant access to the requested resource and returns data based on the permissions associated with your API user.

Request an Access Token

The following parameters are required and must be included in your request.

To initiate the flow, post your client credentials to the token endpoint. You can include the client credentials as parameters as Basic Authorization Header or the request body.

The token endpoints requires the "scope" request parameter which includes your MyPreferences client_Id and userId concatenated using a forward slash as shown below.

ACME_CORP/John.Doe

A sample POST request with the client credentials as Basic Authorization Header.

The client_Id and client_secret should be combined into a string in the format client_id:client_secret, and then Base64-encoded. The resulting string is included in the Authorization header with the value Basic <base64-encoded-string> as shown below.

 
POST /oauth2/v1/token HTTP/1.1
Host: authstg.mypreferences.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Authorization: Basic e3tyZXBsYWNld2l0aGNsaWVudGlkfX06e3tyZXBsYWNld2l0aGNsaWVudHNlY3JldH19
grant_type=client_credentials&scope=ACME_CORP%2FJohn.Doe

A sample POST request with the client credentials in the request body.

 
POST /oauth2/v1/token HTTP/1.1
Host: authstg.mypreferences.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json
grant_type=client_credentials&scope=ACME_CORP%2FJohn.Doe&client_id={{clientid}}&client_secret={{clientsecret}}

The OAuth Token API grants an Access Token

Once your request is validated successfully, the OAuth Token endpoint returns a response containing the access token. Your app can use the access token to access the MyPreferences API.

Here’s a sample access token response in JSON format.

HTTP/1.1 200 OK
Content-Length: 992
Content-Type: application/json; charset=UTF-8
{
  "access_token":"ewogICJhbGciOiJSUzI1NiIsCiAgImtpZCI6InN0YWdpbmctbXlwcmVmX29hdXRoLWp3dC1rZXkiCn0.ewogICJ0b2tlbl90eXBlIjoiQmVhcmVyIiwKICAidXNlcm5hbWUiOiJudWxsIiwKICAiaXNzIjoiaHR0cHM6Ly9hdXRoc3RnLm15cHJlZmVyZW5jZXMuY29tL29hdXRoMi92MSIsCiAgImF1ZCI6WwogICAgImh0dHBzOi8vcG1zdGcubXlwcmVmZXJlbmNlcy5jb20vcHJvZmlsZXMvdjIiCiAgXSwKICAic3ViIjoiT09RSUFfVHJhaW5pbmdfVjIvT09RSUFfVHJhaW5pbmdfVjJfYWR2b2lub3Nfc3RnIiwKICAianRpIjoiYjdjNmExYWZmNDA3NGZkMzMzYmE0MDk0OTAyOGYzNTQwYTU1ZmNhNTdiMjlhNTA5YTNiMTRhNGZmNTFjNzcyYiIsCiAgImlhdCI6MTY5MDgxMzA2NSwKICAiZXhwIjoxNjkkwODEzMzY1LAogICJuYmYiOjE2OTA4MTI3NjUKfQ.tnBS14QlL7iasWx6mCY7f0CtvVY0N1C2QJVuguGNyMtxkRMyJm6RDzJ0c_FlYZA0mpHnUpOGFuN2s-_F_iPehzPwa9wJwmb04BBn_Qa7y4QMRcSUTTlKqHXfaaexdW2risajUiFynuI0PutNJ75fStdXIaEGJUQtE9M8Pkx-yYvP2_xWC1aURqeYREp831-DuK41NeDHObUEDrdqdaOSm7x6LdOUuUqmuBg5uxj4RJwNOAx1gOuTOtH43RuyKpAPS6E6KeXYTivG-ByjDHY4MVSv_ayMx-An7c6jAPeej6qBsgKGeP1X9ukwaRZjKb7XSt71fdiVUD1XfpBEhHrToQ",
  "expires_in":300,
  "token_type":"Bearer",
  "scope":""
} HTTP/1.1 200 OK
Content-Length: 992
Content-Type: application/json; charset=UTF-8
{
  "access_token":"ewogICJhbGciOiJSUzI1NiIsCiAgImtpZCI6InN0YWdpbmctbXlwcmVmX29hdXRoLWp3dC1rZXkiCn0.ewogICJ0b2tlbl90eXBlIjoiQmVhcmVyIiwKICAidXNlcm5hbWUiOiJudWxsIiwKICAiaXNzIjoiaHR0cHM6Ly9hdXRoc3RnLm15cHJlZmVyZW5jZXMuY29tL29hdXRoMi92MSIsCiAgImF1ZCI6WwogICAgImh0dHBzOi8vcG1zdGcubXlwcmVmZXJlbmNlcy5jb20vcHJvZmlsZXMvdjIiCiAgXSwKICAic3ViIjoiT09RSUFfVHJhaW5pbmdfVjIvT09RSUFfVHJhaW5pbmdfVjJfYWR2b2lub3Nfc3RnIiwKICAianRpIjoiYjdjNmExYWZmNDA3NGZkMzMzYmE0MDk0OTAyOGYzNTQwYTU1ZmNhNTdiMjlhNTA5YTNiMTRhNGZmNTFjNzcyYiIsCiAgImlhdCI6MTY5MDgxMzA2NSwKICAiZXhwIjoxNjkkwODEzMzY1LAogICJuYmYiOjE2OTA4MTI3NjUKfQ.tnBS14QlL7iasWx6mCY7f0CtvVY0N1C2QJVuguGNyMtxkRMyJm6RDzJ0c_FlYZA0mpHnUpOGFuN2s-_F_iPehzPwa9wJwmb04BBn_Qa7y4QMRcSUTTlKqHXfaaexdW2risajUiFynuI0PutNJ75fStdXIaEGJUQtE9M8Pkx-yYvP2_xWC1aURqeYREp831-DuK41NeDHObUEDrdqdaOSm7x6LdOUuUqmuBg5uxj4RJwNOAx1gOuTOtH43RuyKpAPS6E6KeXYTivG-ByjDHY4MVSv_ayMx-An7c6jAPeej6qBsgKGeP1X9ukwaRZjKb7XSt71fdiVUD1XfpBEhHrToQ",
  "expires_in":300,
  "token_type":"Bearer",
  "scope":""
} 

The following parameters are included in the response:

Usage of Access Token

In the OAuth Client Credentials Flow, the "Access Token" is a crucial element used to authenticate API requests on behalf of the client application without involving any end-user interaction.

The access token is a JWT string representing the authorization to access MyPreferences API which has a defined scope and an expiration time associated with it. When making API requests you must include the access token in the "Authorization" header of the HTTP request. As shown in the example below, we are using the access token to invoke the Retrieve Programs endpoint.

GET /Profiles/v4/ACME_Corp/Programs HTTP/1.1

Host: pmstg.mypreferences.com
Authorization: Bearer <
access_token
>
Accept: application/json GET /Profiles/v4/ACME_Corp/Programs HTTP/1.1

Host: pmstg.mypreferences.com
Authorization: Bearer <
access_token
>
Accept: application/json 

Once the access token is included in your API request, you will be granted access to the MyPreferences API depending on the permissions associated with the user making the API call.

Access Tokens have a limited lifespan known as the “expiration time” which is currently set to 60 minutes and can be configured on a per client basis. Once expired, the token becomes invalid, and the client must request a new access token using the same client credentials. Access Tokens should be treated as sensitive information and securely managed by the client application. It's essential to avoid exposing tokens in logs, URLs, or public repositories. Secure transmission over HTTPS is mandatory to prevent token interception. If you suspect the token has been compromised or no longer needed, please send a revocation request to support (support@possiblenow.com) immediately to invalidate the token.

Using Certificate instead of Client Secret

In the OAuth 2.0 Client Credentials flow, you can use certificate instead of a client secret to authenticate your access request with the authorization server.

Instead of sending your client ID and client secret in the request to the token endpoint, you will be required to send the certificate during the authentication process. The certificate contains the public key, which the authorization server will use to verify your identity.

To use a client certificate for authentication, you must be registered with the authorization server, and the public key corresponding to the client certificate must be associated with your account's registration.

The steps in the flow remain the same, but instead of providing a client secret, you will send the certificate as part of your authorization request. The OAuth token endpoint validates the certificate and returns an access token if the certificate is successfully verified.

Using a client certificate for authentication can be beneficial in scenarios where you want to avoid sending sensitive information (like a client secret) over the network.

Authorization Header

You can also access the MyPreferences API using our custom authorization scheme. This requires you to include an authorization field in the HTTP Header for all types of requests. This authorization field should contain the appropriate scheme and relevant parameters, adhering to the format specified by RFC 7235. The scheme and parameters within the Authorization Header should be separated by a space, as per the defined guidelines.

Authorization: <scheme> <parameters>

Currently there are two scheme types and one available scheme identifier for authorization. Additional schemes may be added to address any weaknesses in the authorization header by adding or removing additional parameters. The authorization scheme types allow for a keyed hash and un-keyed hash.

It is highly recommended that the keyed hash scheme be used whenever possible as it is more secure. Please note that the authorization scheme is case insensitive. An example of each of the two scheme types is shown below:

The SchemeIdentifier drives and defines the authorization process and parameters. Each available scheme identifier will be addressed in the following sections.

The CryptoHashIdentifier is the name of the hash algorithm that is used to generate the signature parameter in all of the scheme authorization parameters. The following hash functions from the SHA-2 family are currently available:

• SHA256
• SHA384
• SHA512

Available Schemes

• 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/api/3/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)