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.
Before you begin, you will require a unique client_id and client_secret for your app. Notify your Implementation Manager or PossibleNOW Support at support@possiblenow.com requesting an OAuth client_id and client_secret. Include your MyPreferences Client ID and the environment (Staging (Sandbox) / Production) for which you want to generate the credentials in your request. These credentials must be treated securely.
OAuth Flow
- Send client credentials to the MyPreferences OAuth Token API via a POST request.
- The OAuth Token API validates the client credentials and returns an access token.
- You can now use the access token to access MyPreferences REST API.
- The MyPreferences REST API will grant access to the requested resource and returns data based on the permissions associated with your API user.
OAuth Token endpoints:
Staging: https://authstg.mypreferences.com/oauth2/v1/token
Production: https://auth.mypreferences.com/oauth2/v1/token
Request an Access Token
The following parameters are required and must be included in your request.
Parameter | Description |
client_id | A 48-character static string that represents the OAuth client id. Note: This is the OAuth Client Id which is different than the MyPreferences Client Id. The MyPreferences Client Id is a required path parameter on all MyPreferences REST API's. |
client_secret | A 64-character randomized secret key. The client secret can be rotated on a regular basis for enhanced security. You can also utilize a certificate in place of the client secret. See below for more details. |
scope | Scope associated with the access request. This should include the MyPreferences |
grant_type | This represents the OAuth 2.0 grant type which must be set to Client Credentials. |
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 e3tyZXBsYWNld2l0aGNsaWVudGlkfX06e3tyZXBsYWNld2l0aGNsaWVudHNlY3JldH19grant_type=client_credentials&scope=ACME_CORP%2FJohn.DoeA sample POST request with the client credentials in the request body.
POST /oauth2/v1/token HTTP/1.1Host: authstg.mypreferences.comContent-Type: application/x-www-form-urlencodedAccept: application/jsongrant_type=client_credentials&scope=ACME_CORP%2FJohn.Doe&client_id={{clientid}}&client_secret={{clientsecret}}The OAuth 2.0 Client Credentials flow does not support the use of refresh tokens.
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.
The following parameters are included in the response:
Parameter | Description |
access_token | OAuth token that can be used to access MyPreferences API. Access to resources depends on the permissions associated with the |
token_type | Indicates the type of access token being returned. MyPreferences OAuth token endpoint will always return a Bearer token type. |
scope | Scope associated with the access token. |
expires_in | Amount of time remaining (in seconds) before the access token expires. |
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.
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.
You must cache the access token to avoid repeated requests before the token expires.
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.
Notify PossibleNOW Support to register your account for using client certificate.
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.
On this page
- OAuth