OAuth

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":""
} 

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 

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.