How enrollment and fallback work

CP Word List runs at two moments in a Cloudpath enrollment: an invisible notification that changes the DPSK, and the display page the user sees. This page explains what happens in each case, and why the service can never stop someone from getting online.

First enrollment

When a user enrolls for the first time:

1. Cloudpath generates the DPSK — a random string like x8kP2mQ9.
2. The notification fires. Cloudpath calls /api/change-dpsk with the enrollment ID (${GUID}) and your Shared Secret. CP Word List authenticates to your Cloudpath server, looks up the DPSK for that enrollment, generates a memorable phrase like apple-red-truck, and updates the DPSK on the controller.
3. The mapping is cached — the old random string mapped to the new phrase — and can be looked up for 5 minutes.
4. The display page loads. Its snippet takes the old DPSK from Cloudpath’s ${DPSK} variable and calls /api/get-dpsk to fetch the new phrase, then shows it and the SSID to connect to.

The user reads apple-red-truck off the screen and connects.

Re-enrollment

When a returning user re-enrolls, their DPSK is often already in word-list format. CP Word List handles this gracefully:

• The notification step still fires. The service does not check whether the DPSK is already word-based: it skips the change only when a device is already connected on the DPSK (409) or no DPSK is found for the enrollment (404). Either way it’s invisible to the user.
• The display snippet detects that the DPSK is already in word-word-word format and shows it immediately, with no API call.

That means CP Word List is not a dependency for returning users viewing their existing passphrase.

Caution

If a returning user’s word-based DPSK has no device connected, the notification replaces it with a new phrase, but the display page still shows the old word-based one it received from Cloudpath. The new phrase is the one set on the DPSK in Cloudpath.

The 5-minute cache

The old-to-new passphrase mapping is cached for 5 minutes so the display page can look it up. The display page polls during this window. After 5 minutes the mapping expires — but the new passphrase is already set on the controller and stays active indefinitely. A scheduled job runs every 5 minutes and deletes expired mappings, so no mapping is stored for more than about 10 minutes.

Downtime never blocks network access

CP Word List is an enhancement layer. It cannot prevent anyone from connecting: whichever passphrase is on the DPSK in Cloudpath — the original, or the word-based one after a change — is valid. If the service is unreachable or erroring:

• The passphrase change never happens, so the original Cloudpath passphrase stays valid. The display snippet waits up to 15 seconds (polling up to 7 times), then falls back to showing that original Cloudpath passphrase — a working credential.
• For returning users whose DPSK is already word-based, no API call is made at all — the passphrase shows instantly.

The only effect of an outage is that a new enrollment sees a random passphrase instead of a memorable one. Network connectivity is never affected.

Caution

The fallback shows the original passphrase whenever the snippet gets no new phrase within 15 seconds — including the case where the change succeeded but the lookup failed or was slow. That original passphrase has already been replaced and no longer works. The new word-based passphrase is on the DPSK in Cloudpath.

Next steps

• HTTP API reference — the underlying endpoints and the Cloudpath REST API calls behind each step above.
• Passphrase format and strength — what the generated phrase looks like and how it’s chosen.
• Troubleshooting — if a test enrollment still shows a random string.