Skip to content

Preference Wallet

Overview

In this guide, you'll learn how to embed the One Creation Preference Wallet into your platform. To ensure a secure and personalized experience, the Preference Wallet should be placed after your consumer authentication process. One Creation will establish a secure connection with your platform using OAuth PKCE and dynamically display relevant campaigns to the authenticated users that your platform has provided.

1. Setup OAuth

1.1. Get Authorization Code

  1. Log in to One Creation.
  2. Navigate to Settings –> Preference Wallet. You need to be an organization Admin to access this page.

  3. You will see pre-generated Client key and Client secret for your organization. The "Client secret" does not expire unless you click on the "Regenerate credentials" button.

  4. Use the Client key and Client secret to retrieve an authorization code.

    Query parameter Description
    response_type Set to code.
    client_id. The Client key
    redirect_uri The URL where your application receives an authorization code.
    code_challenge_method Set to S256.
    code_challenge A cryptographically random string generated by you. This ensures One Creation can validate the client exchanging the authorization code is the same client that originally requested it and that the authorization code hasn't been stolen and injected into a different session. See Code Challenge and PKCE section for details

    Here is an example request including all parameters: 

    
  https://api.one-creation.com/authentication/oauth/authorize?response_type=code
  &client_id=client_id
  &redirect_uri=https://your-website.com/callback&code_challenge_method=S256
  &code_challenge=hjfhfdldfidalf

1.2. Request Access Token

  • Access Token: An access token grants temporary access to a One Creation organization account. It can be up to 4,096 characters long, so plan your storage accordingly. Its validity period is specified by the expires_in value returned by the https://api.one-creation.com/authentication/oauth/token endpoint. Always rely on this value to determine expiration.
  • Refresh Token: A refresh token is issued upon successful authorization and remains valid until you revoke the integration using the https://api.one-creation.com/authentication/oauth/revoke endpoint. If you revoke a refresh token, it revokes the access token as well, and the integration is no longer valid.

Once you have the authorization code from the user, follow these steps to exchange it for access and refresh tokens:

  1. Use a Server-to-Server Request: The client secret is confidential and should never be exposed to the user's browser to protect their data.
  2. Check Client Secret: If you haven't saved your client secret, generate a new one through the One Creation GUI and add it to your application's environment settings.
  3. Set Content-Type: Ensure the request body is formatted as application/x-www-form-urlencoded. Avoid using JSON, as it can lead to errors.

  4. Send a POST request to this endpoint URL: https://api.one-creation.com/authentication/oauth/token

    Request Header Value
    Authorization (Required) A base64-encoded string containing the client ID and client secret key. The format must be: Authorization: Basic <base64 encoded client_id:client_secret>
    Content-Type (Required) Set to application/x-www-form-urlencoded.

    Request Body Value
    grant_type Must be authorization_code.
    code The authorization code.
    code_verifier This is the plain-text random string you used to generate the code_challenge in your authorization request. One Creation hashes this value to verify that it matches the code_challeng you sent in the authorization request that created this code.
    redirect_uri This must be the same redirect_uri that you used in the authorization request to acquire this code. If there is a mismatch, this request will fail.
    5. If your request is successful, you’ll receive the following response:
    Key Type Description
    access_token String A One Creation generated token that can be used in the Authorization header for calling the API instead of an API key.
    refresh_token String A One Creation generated token that can be used to request a new access token and refresh token.
    expires_at Date The timestamp of when the access token expires.
    6. If your request fails, here are some common error messages you may encounter:
    Error Description Reason
    Invalid authorization The authorization header is missing or invalid.
    Invalid grant_type The grant_type parameter is invalid.
    Unsupported_grant_type The grant_type parameter is not authorization_code.
    Invalid code The code parameter is invalid.
    Invalid code_verifier The code_verifier parameter is invalid.
    Invalid redirect_uri The redirect_uri parameter is invalid.

2. Embed Preference Wallet

  1. Log in to One Creation.
  2. Navigate to Settings –> Preference Wallet. You need to be an organization Admin to access this page.

  3. You'll see a preview of its appearance. This preview gives you a general idea of its layout.

    • You can personalize the wallet to match your brand or webpage's style. This includes:
      • Colors: Change the background, text, and other elements to align with your brand palette.
      • Font: Select a font that complements your website's typography.
    • The preference wallet has three main navigation pages:
      • Thumbnail: This is a prompt page titled "Underatand Your Data", inviting users to click for more information about their data sharing and controls. By default, it's hidden. To show it, click the "Show Thumbnail Page" switch.
      • What We've Collected: Displays a list of campaigns that the user has shared.
      • Detail Page: Allows the user to view specific campaign details.

  4. Once you've finished customizing the wallet, click Copy under the Embed Code

  5. Paste the copied code into the desired webpage where you'd like to embed the preference wallet.

      // the embed code
  <div id="oc-embed-container"></div>
  <script src="<%= APP_URL %>/embed/oc-preference-center.min.js"></script>
  //Pass your access token and the authenticated consumer ID here
  <script>
      document.addEventListener("DOMContentLoaded", function () {
        if (OCPreferenceCenter) {
          const token = document.getElementById("your-token-id-element").value;
          const email = document.getElementById("your-consumer-id-element").value;
          OCPreferenceCenter.setCredentials({ token, email });
        }
      });
  </script>

  6. Now you are ready to test. Log in to your webpage as a valid user/consumer, access the preference wallet, and it should display the campaigns you've agreed to share data with. You'll see details of individual data points and their expiration dates. Here's an example of a preference wallet embedded within the user profile.

3. Code Challenge and PKCE

3.1. Generate Code Verifier and Challenge

One Creation requires PKCE, a recommended security measure for all OAuth client types. PKCE consists of two components:

  • code_verifier: A randomly generated string, typically between 43 and 128 characters long, containing letters, digits, underscores, periods, hyphens, or tildes.
  • code_challenge: The SHA-256 hash of the code_verifier.

Before creating your authorization URL, you'll need to generate both the code verifier and code challenge.

Here's a Python example demonstrating how to create these:


  import os
  import hashlib
  import base64

  verifier_bytes = os.urandom(32)
  code_verifier = base64.urlsafe_b64encode(verifier_bytes).rstrip(b'=').decode('utf-8')
  challenge_bytes = hashlib.sha256(code_verifier.encode()).digest()
  code_challenge = base64.urlsafe_b64encode(challenge_bytes).rstrip(b'=').decode('utf-8')

If you encounter an "Invalid code_verifier" error, ensure your code verifier adheres to the following regular expression pattern:

r'^[a-zA-Z0-9\-._~]{43,128}$'

This pattern enforces the specified requirements for code verifiers.

For each new authorization URL, you must generate a fresh code verifier and code challenge pair to maintain security.

3.2. Store PKCE Values Across Requests

When we redirect to your redirect_uri with the authorization code, you will exchange this code for an access token. In this exchange, you'll also need to provide the code_verifier to verify it against the code_challenge used in the authorization request.

To achieve this:

  1. Save the code_verifier in a secure data store (e.g., database, cache).
  2. Use the stored code_verifier to exchange the authorization code for an access token.

3.3. Common Error Messages

Error Description Reason
Invalid response_type The response_type parameter is invalid or does not equal code.
Invalid client_id The client_id parameter is invalid.
Invalid redirect_uri The redirect_uri parameter is invalid.
Invalid code_challenge_method The code_challenge_method is invalid or does not equal S256.

4. Refresh Tokens

When your access token expires, you can obtain a new one using a refresh token. Here's how:

  1. Send a POST request to the endpoint: https://api.one-creation.com/authentication/oauth/refresh
  2. Include the refresh token you received during the initial authorization flow in the request body.

  3. The request structure is similar to exchanging an authorization code, but you'll use the refresh token instead.

    Request Header Value
    Authorization (Required) A base64-encoded string containing the client ID and client secret key. The format must be: Authorization: Basic <base64 encoded client_id:client_secret>
    Content-Type (Required) Set to application/x-www-form-urlencoded.

    Request Body Value
    grant_type Must be authorization_refresh.
    refresh_token The refresh_token to be used to generate a new valid access_token.

Common Error Messages:

Error Description Reason
Invalid authorization The authorization header is missing or invalid.
Invalid grant_type The grant_type parameter is invalid.
Unsupported_grant_type The grant_type parameter is not authorization_code.
Invalid refresh_token The refresh_tokem parameter is invalid.

5. Revoke an Application

You may want to revoke your application's access in scenarios like:

  • Uninstalling the integration from One Creation
  • Security concerns requiring a complete access reset

Note: This action removes your application's integration and invalidates all tokens associated with it.

To revoke your application's access, send a POST request to https://api.one-creation.com/authentication/oauth/revoke

Request Headers Value
Authorization (Required) A base64-encoded string containing the client ID and client secret key. The format must be: Authorization: Basic <base64 encoded client_id:client_secret>
Content-Type (Required) Set to application/x-www-form-urlencoded.
Request Body Value
grant_type Must be authorization_revoke.

Common Error Messages:

Error Description Reason
Invalid authorization The authorization header is missing or invalid.
Invalid grant_type The grant_type parameter is invalid.
Unsupported_grant_type The grant_type parameter is not authorization_revoke.

6. Troubleshooting Tips

6.1. Invalid Client

If you encounter an invalid_client error:

  • Ensure your client ID is correct.
  • Confirm that [ID]:[SECRET] is properly base64 encoded.
  • Inspect Authorization header and verify that the prefix "Basic" is also base64 encoded, and that the concatenated string is correctly formatted. Some languages might require special handling for encoded data. Ensure the authorization header in your request looks like this: Authorization: Basic <base64 encoded client_id:client_secret>.

6.2. Invalid Grant Type

If you encounter an invalid_grant_type error:

  • Ensure you’re using the correct grant type. For example: authorization_code, refresh_token.
  • Confirm that the request body's Content-Type is application/x-www-form-urlencoded.
  • Double check the request body's format and encoding to ensure it's correct for your programming language.
  • If you're using a refresh token and the request appears correct, the refresh token might be invalid due to expiration or revocation.

6.3. Invalid Code Verifier

If you encounter an Invalid "code_verifier" error, ensure your code verifier adheres to the following regular expression pattern: 

r'^[a-zA-Z0-9\-._~]{43,128}$'

6.4. Code Challenge Failed

If you encounter a Code challenge failed error for an /oauth/token request, it indicates a mismatch between the hashed code_verifier and the code_challenge originally provided in the authorization request.

Double-check the following:

  • Ensure you're sending the correct code_verifier.
  • Verify that you're hashing the code_verifier using the SHA-256 algorithm.
Last update: September 25, 2024