Integrate ContextPass in 10 Minutes

Add personalization without profiling to your store

1Sign up and get your keys

Create your merchant account and get your public and secret keys.

Visit the merchant dashboard to sign up. You'll receive two keys:

Save your secret key immediately. It's shown only once during signup. If you lose it, you'll need to rotate your keys.

2Drop in the script tag

Add this script tag to your store's page:

<script src="https://cdn.contextpass.io/v0.1/contextpass.js"></script>

Then initialize the SDK with your public key:

<script>
ContextPass.init({
  publicKey: 'cp_pk_your_key_here'
});
</script>

3Request fields when you need them

Call requestFields() when you want the user's context. For example, on page load or when they click "Personalize":

<button id="personalizeBtn">Get Personalized Recommendations</button>

<script>
document.getElementById('personalizeBtn').addEventListener('click', async () => {
  const result = await ContextPass.requestFields(
    ['size', 'budget'],
    {
      purpose: 'Find items in your size and price range',
      retention: 'temporary'  // or 'permanent'
    }
  );

  if (result.approved) {
    console.log('Grant created:', result.grantId);
    // Send grantId to your backend
    await fetch('/api/personalize', {
      method: 'POST',
      body: JSON.stringify({ grantId: result.grantId })
    });
  } else {
    console.log('User denied:', result.reason);
  }
});
</script>
What's a grant? A grant is a temporary authorization to access specific fields. The user controls it—they can see and revoke it anytime.

4Exchange grants server-side

Your backend receives the grantId and exchanges it for the actual field values using your secret key:

// Node.js example
const response = await fetch('https://api.contextpass.io/v1/tokens/exchange', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer cp_sk_your_secret_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ grant_id: grantId })
});

const { fields } = await response.json();
console.log(fields); // { size: 'M', budget: '500' }
Never expose your secret key in browsers. Always exchange grants server-side.

Webhook Events

When important events happen, ContextPass sends webhooks to your endpoint. (Coming in v0.2)

Event Payload When
cp:fields-approved { grantId, pairwiseId, fields } User approved field request
cp:fields-denied { fields, reason } User denied field request
cp:grant-revoked { grantId } User revoked a grant
cp:token-exchanged { grantId, pairwiseId } Your backend exchanged a grant

API Reference

POST /v1/merchants

Sign up a new merchant (you do this via the dashboard).

POST /v1/grants

Browser SDK: Create a grant after user approves consent.

Auth: Authorization: Bearer cp_pk_*

POST /v1/grants/:id/revoke

Revoke a grant (can use public or secret key).

POST /v1/tokens/exchange

Server-side: Exchange grant for field values.

Auth: Authorization: Bearer cp_sk_* (secret key only)

Getting Help