Overview
What is this? Success Center authentication controls who can open a Success Center. When a contact opens one, ChurnZero sends the browser to a sign-in endpoint that you build, which confirms who the contact is and hands them back to ChurnZero.
With Success Center groupings, you can show different Success Centers in different products. Each product can have its own sign-in endpoint and its own secret, so each product's developers can sign their users in through that product's own login. Products that don't need their own sign-in share one Default Endpoint.
Who is this for?
- ChurnZero admins who set up groupings and their authentication endpoints. See Set Up Authentication in ChurnZero.
- Developers who build each product's sign-in endpoint and add the ChurnZero JavaScript. See Build Your Authentication Endpoint and ChurnZero JavaScript Commands for Success Centers.
Prerequisite: install the ChurnZero JavaScript in your product before you set up Success Center authentication.
Key Concepts
- Grouping: an ordered list of Success Centers. Contacts see the first active Success Center they qualify for, starting from the top. Every account has a Default grouping.
- Application key (App Key): the key your product passes to the ChurnZero JavaScript. The application key decides which grouping a contact sees and which sign-in endpoint and secret ChurnZero uses.
- Endpoint: an application key with its own Authentication URL and Secret, added on a grouping's Authentication tab. Adding an endpoint creates a new application key in that grouping.
- Default Endpoint: the shared login. Any application key without its own endpoint uses it, and that key shows the Default grouping's Success Centers.
Which endpoint and secret ChurnZero uses
| The application key on the page… | Contacts see Success Centers from… | ChurnZero sends contacts to… | Your endpoint signs requests with… |
|---|---|---|---|
| Has its own endpoint | The grouping the endpoint belongs to | The endpoint's Authentication URL | The endpoint's secret |
| Has no endpoint (for example, an application key you already used before groupings) | The Default grouping | The Default Endpoint's Authentication URL | The Default Endpoint's hash secret |
Each product's sign-in endpoint must send the same application key that the product's pages use, and sign its request with that key's secret. ChurnZero picks the secret from the application key in the request.
If ChurnZero can't find both a URL and a secret for an application key, contacts on pages with that key don't see the Success Center launcher at all. Set up the endpoint first, then the launcher appears.
How sign-in works
- A user in your product opens the Success Center. The page has loaded the ChurnZero JavaScript with an application key and the user's account and contact external IDs.
- ChurnZero sends the browser to the Authentication URL for that application key, with a one-time
nextvalue. - Your endpoint confirms who the user is in your product, then asks ChurnZero for a one-time token with a request signed with that application key's secret.
- Your endpoint sends the browser back to ChurnZero with the token and the
nextvalue. ChurnZero signs the contact in and opens the Success Center.
ChurnZero builds the Success Center's own address and shows it in a frame on your page or in a new tab. Your developers don't create or supply that address.
Set Up Authentication in ChurnZero
Prerequisites
- To add, edit or delete endpoints, or to change the Default Endpoint, you need the Developer Tools permission at Full access.
- To see a grouping's Authentication tab, you need Success Center Management or Developer Tools at Full access.
- Users with Secure Access can't see or change Success Center authentication.
Open a grouping's Authentication tab
- Go to Digital Tools > Success Centers.
- If your account has more than one grouping, select the grouping on the Success Center Groupings page.
- Select the Authentication tab.
The tab lists the grouping's endpoints, with columns Application Key Name, Key, Authentication URL and Secret. The Default Endpoint is shown below the list on every grouping's tab.
Set up the Default Endpoint
- On any grouping's Authentication tab, select Edit Default Endpoint.
- Enter the Authentication URL. It must be an
httpsaddress. - Enter a Hash secret. If a secret is already set, select Replace Secret first; the current secret keeps working until you save.
- Select Save, then Confirm. The change applies to every application key without its own endpoint, in every grouping.
- If you entered a new secret, the Secret Saved window shows it. Select Copy and give it to your developers. This is the only time ChurnZero shows it.
Check: the Default Endpoint box shows your URL and a Set label next to it.
Tips:
- To send each customer to their own domain, add a merge field to the URL. Choose an account or contact field under Merge field, select Copy, and paste it into the Authentication URL, for example
https://{{Account.externalId}}.example.com/cz-login(shown in the picker as Account ExternalId). You can use standard and custom account and contact fields. See also Multi-Tenant Authentication for Success Centers. - In the domain part of the URL, ChurnZero keeps only the letters, digits, hyphens and periods from a merge field's value. In the rest of the URL, the value is URL-encoded. ChurnZero doesn't check a URL with merge fields when you save it, so test it with a real contact.
- Clearing the URL turns the Default Endpoint off. Contacts on pages whose application key has no endpoint then stop seeing the Success Center launcher.
Add an endpoint for a product
- Open the Authentication tab of the grouping whose Success Centers this product should show.
- Select Add Endpoint.
- Enter an Application Key Name, for example the product's name. The name must be unique across your account's application keys and can be up to 500 characters.
- Enter the Authentication URL of the product's sign-in endpoint. It must be an
httpsaddress. It can also contain merge fields. - Enter a Secret. Your developers sign requests with it.
- Select Save. The Endpoint Added window shows the secret. Copy it with the copy button and give it to your developers. This is the only time ChurnZero shows it.
Check: the new row appears with a Set label in the Secret column. Use the copy button in the Key column to copy the new application key for your developers.
Tips:
- Adding an endpoint always creates a new application key. Your product's pages must use this new key for contacts to see this grouping. A key you already use keeps showing the Default grouping through the Default Endpoint.
- The new application key works only with the ChurnZero JavaScript and the Success Center sign-in. The HTTP API, batch file uploads and webhooks refuse it as an unknown key, so keep using your existing application key for those.
- Your developers can reuse their existing authentication code at the new URL. Only the application key and the secret change.
- A grouping with no endpoint shows Setup Incomplete on the Success Center Groupings page. Contacts can't see that grouping until it has an application key.
- Use a long, random secret.
Change or remove an endpoint
- Change the URL or secret: open the row's actions menu and select Edit. Under Replace secret, enter a new secret, or leave it blank to keep the current one. You can't rename an endpoint's application key here.
- Delete an endpoint: open the row's actions menu and select Delete, then Confirm. The application key is kept. Visitors on pages with that key then sign in through the Default Endpoint and see the Default grouping's Success Centers.
- Delete a grouping: its endpoints are removed too, and their application keys move to the Default grouping and the Default Endpoint.
- Delete the application key itself: on the Application Keys page (Admin > Data > Application Keys), a key with an endpoint can't be deleted. Delete the endpoint on the grouping's Authentication tab first.
Changing a secret takes effect as soon as you save. Requests your endpoint signs with the old secret then fail. Coordinate a secret change with your developers.
Build Your Authentication Endpoint
This section is for the developers who build the sign-in endpoint for a product. If you already have a Success Center endpoint for the Default Endpoint, you can reuse it for a new product: point the new endpoint's URL at it and switch the application key and secret per product.
What you need from your ChurnZero admin
- The product's application key (from the Key column of the grouping's Authentication tab). For a product that uses the Default Endpoint, use the application key you already have.
- The secret for that key's endpoint, or the Default Endpoint's hash secret.
Step 1: Load the ChurnZero JavaScript with the product's application key
On every page of the product, after the standard ChurnZero JavaScript snippet, set the product's application key and the signed-in user:
ChurnZero.push(['setAppKey', 'YOUR_PRODUCT_APP_KEY']); ChurnZero.push(['setContact', 'ACCOUNT_EXTERNAL_ID', 'CONTACT_EXTERNAL_ID']);
The application key decides which grouping's Success Centers the user sees. Use the same account and contact external IDs here and in Step 3.
Step 2: Receive the sign-in request
When a user who isn't signed in opens the Success Center, ChurnZero sends the browser to your Authentication URL with a next query parameter:
https://login.example.com/cz-login?next=4f6c0e2a9b1d4c7e8a3b5d6f7a8b9c0d
Keep the next value; you send it back in Step 4. If your URL already has a query string, ChurnZero adds &next=… instead.
Your endpoint confirms who the user is in one of two ways:
- Your own cookie: the browser sends your product's cookies to your endpoint, so an endpoint on your product's domain can read the user's existing sign-in. No extra code is needed in the page.
-
A token from the page: pass a token from your product with
setAuth. See Pass your own values to your endpoint.
Your endpoint should recognize a user who is already signed in to your product and continue without asking them to sign in again. When the Success Center opens inside your product, this step runs in a small browser window.
The next value expires one minute after ChurnZero creates it. If the user has to sign in to your product first and takes longer, the last step fails, and the user opens the Success Center again.
Step 3: Request a token from ChurnZero
Send a POST request to https://your-churnzero-vanity-url/SuccessCenterContactLookup with a JSON body and an X-Signature header.
| Field | Value |
|---|---|
appKey |
The product's application key, the same key the page uses. |
accountExternalId |
The user's account external ID. |
contactExternalId |
The user's contact external ID. |
The X-Signature header is the HMAC-SHA256 of the exact request body, keyed with the secret for that application key, written as hexadecimal (see How do I generate HMACs?). Sign the exact string you send: if you change the body after signing (for example, by serializing it again), the signature no longer matches.
If no contact matches the external IDs, ChurnZero adds one. A successful response is:
{ "authToken": "…" }The token can be used once and expires after one minute.
Step 4: Send the user back to ChurnZero
Redirect the browser to:
https://your-churnzero-vanity-url/SuccessCenterCallback?token=<authToken>&next=<next>
URL-encode both values. ChurnZero signs the contact in and opens the Success Center they asked for.
Example
This example uses Node.js 18 or later (for the built-in fetch) and Express 4. Replace the session check with your own sign-in logic. Keep the secret on your server; never put it in browser code.
const crypto = require('crypto');
const express = require('express');
const app = express();
const CZ_DOMAIN = 'https://your-churnzero-vanity-url'; // your ChurnZero vanity URL
const APP_KEY = process.env.CZ_APP_KEY; // this product's application key
const SECRET = process.env.CZ_SC_SECRET; // the secret for that key
app.get('/cz-login', async (req, res) => {
const next = req.query.next;
if (typeof next !== 'string' || !next) {
return res.status(400).send('Missing next.');
}
const user = req.session && req.session.user; // your own sign-in check
if (!user) {
return res.redirect('/login?returnTo=' + encodeURIComponent(req.originalUrl));
}
const body = JSON.stringify({
appKey: APP_KEY,
accountExternalId: user.accountExternalId,
contactExternalId: user.contactExternalId,
});
const signature = crypto.createHmac('sha256', SECRET).update(body).digest('hex');
try {
const lookup = await fetch(`${CZ_DOMAIN}/SuccessCenterContactLookup`, {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'X-Signature': signature },
body,
});
if (!lookup.ok) {
console.error('ChurnZero token request failed', lookup.status, await lookup.text());
return res.status(502).send('The Success Center could not be opened.');
}
const { authToken } = await lookup.json();
res.redirect(`${CZ_DOMAIN}/SuccessCenterCallback?token=${encodeURIComponent(authToken)}&next=${encodeURIComponent(next)}`);
} catch (err) {
// Express 4 doesn't catch errors from async handlers, so handle them here.
console.error('ChurnZero token request failed', err);
res.status(502).send('The Success Center could not be opened.');
}
});Pass your own values to your endpoint
If your endpoint needs extra values from the page, such as a token from your own app, register a function with setAuth before you call setContact. The function returns an object of names and text values; ChurnZero adds each one to your Authentication URL as a query parameter.
ChurnZero.push(['setAuth', function () {
return { sessionToken: getMyAppToken() };
}]);Your endpoint then receives, for example, ?next=…&sessionToken=…. ChurnZero calls the function when it starts sign-in, so it can return a current token. Return at least one value.
ChurnZero JavaScript Commands for Success Centers
Send each command with ChurnZero.push([...]). Command and event names are not case-sensitive.
| Command | What it does |
|---|---|
ChurnZero.push(['open']) |
Opens the contact's Success Center, for example from your own button. |
ChurnZero.push(['close']) |
Closes it. |
ChurnZero.push(['setAuth', fn]) |
Registers the function that supplies extra values for your Authentication URL. See Pass your own values to your endpoint. |
ChurnZero.push(['ChurnZeroEvent:on', eventName, callback]) |
Registers a callback for connected or unreadMessagesUpdate. |
ChurnZero.push(['ChurnZeroEvent:off', eventName, callback]) |
Removes that callback. Leave out the callback to remove every callback for the event. |
When you register a callback, ChurnZero calls it at once with the last value it sent for that event. If the event hasn't fired yet while a callback was registered, the first call receives undefined. Register your callbacks right after the ChurnZero JavaScript snippet, and check for undefined.
connected
Fires each time the ChurnZero JavaScript connects to ChurnZero, for example after the page loads. The callback receives an object with one field:
-
hasCenter:truewhen this contact has a Success Center to show. It isfalsewhen the contact doesn't qualify for an active Success Center in the key's grouping, or when ChurnZero has no Authentication URL or no secret for the application key.
Use it to hide your own link or button to the Success Center when there is nothing to open.
ChurnZero.push(['ChurnZeroEvent:on', 'connected', function (data) {
if (data) {
document.getElementById('help-center-link').hidden = !data.hasCenter;
}
}]);unreadMessagesUpdate
Reports how many unread messages wait in the contact's Success Center. The callback receives an object with one field:
-
count: the number of unread announcements plus the number of unread surveys. Announcements count only when the Success Center has an announcements widget, and surveys only when it has a surveys widget. It is0when there are no unread messages.
It fires only for a contact who has a Success Center:
- once, when the Success Center launcher loads on the page;
- when a new announcement or survey arrives, or one expires, before the contact has opened the Success Center;
- when the open Success Center updates its unread counts, for example after the contact reads an announcement.
ChurnZero.push(['ChurnZeroEvent:on', 'unreadMessagesUpdate', function (data) {
if (data) {
document.getElementById('help-center-badge').textContent = data.count || '';
}
}]);Troubleshooting
| Problem | Cause and fix |
|---|---|
The Success Center launcher doesn't appear in a product, or connected reports hasCenter: false. |
ChurnZero has no Authentication URL or no secret for the page's application key, or the contact doesn't qualify for an active Success Center in that grouping. Check that the key has an endpoint with a secret set, or that the Default Endpoint has both a URL and a Set secret. |
| Contacts see the Default grouping's Success Centers instead of the product's. | The page uses an application key with no endpoint. Use the application key shown on the grouping's Authentication tab in setAppKey. |
| The page shows "Success Center Endpoint URL not configured for Tenant." | There is no Authentication URL for the application key and the Default Endpoint is empty. Add an endpoint or set the Default Endpoint. |
| The page shows "Success Center Endpoint URL resolved errantly for this contact." | The Authentication URL has a merge field that didn't produce a valid web address for this contact, for example because the field is empty. Fill the field for that account or contact, or change the URL. |
| The token request returns HTTP 400 with "Lookup request missing '…'". | The body is missing appKey, accountExternalId or contactExternalId. The message names the missing fields. |
| The token request returns HTTP 401 ("Unauthorized Access [1]"). | The signature doesn't match, or ChurnZero has no secret for that application key. Check that the endpoint sends the product's application key and signs the exact body it sends with that key's secret. After you add an endpoint or replace a secret, update both the key and the secret in your endpoint. |
| The browser shows "Invalid request." after your endpoint redirects back. | The token or the next value expired or was already used. Each lasts one minute and works once. Open the Success Center again. |
| The browser keeps returning to your sign-in endpoint. | The external IDs in the token request don't match the ones the page passed to setContact, so ChurnZero signs in a different contact. Use the same account and contact external IDs in both places. |
| Data sent with the new application key over the HTTP API, batch uploads or webhooks is refused. | Application keys created with Add Endpoint work only with the ChurnZero JavaScript. Use another application key for those. |
A connected or unreadMessagesUpdate callback receives undefined. |
The callback was registered before the event first fired. Check for undefined and wait for the next call. |
FAQs
Q: Do I need an endpoint for every grouping?
A: A grouping needs at least one endpoint before contacts can see it. The Default grouping is reached through any application key without an endpoint, using the Default Endpoint.
Q: Can I move an application key I already use into a new grouping?
A: No. Adding an endpoint creates a new application key. Update the product's pages to use the new key.
Q: Can two products share one grouping?
A: Yes. Add an endpoint for each product on the same grouping. Each gets its own application key, URL and secret.
Q: If a contact signs in through one product, are they signed in to the Success Centers of other products too?
A: Each Success Center signs the contact in through the endpoint for its own grouping when it opens. If the contact is already logged in to that product, this happens without a prompt.
Q: We set up Success Center authentication before groupings. What happens to our existing URL and secret?
A: Your existing authentication URL and secret are now your Default Endpoint. Nothing needs to change in your application.
Q: Can I reuse my existing endpoint for a new product?
A: Yes. Point the new endpoint's URL at it, and have it send the new application key and sign with the new secret.
Comments
0 comments
Article is closed for comments.