Contentpass Token

This page explains what the Contentpass token is and how publishers can use it to detect Contentpass users.

What is the Contentpass token?

Contentpass uses the OpenID Connect (OIDC) standard for account management. Publishers typically do not interact with OIDC directly, as our auth service provides a simplified layer on top.

The standard uses JSON Web Tokens (JWT) to store session information client-side. These compact JSON objects contain a payload with user and session details. Each token is cryptographically signed by our server, ensuring it cannot be tampered with. By keeping session state on the user's device, this approach significantly reduces server requests.

The OIDC standard supports personalized ID tokens containing user-specific information such as email addresses or user IDs. Contentpass deliberately deviates here: our token is anonymized, contains no personal information, and prevents tracking across participating websites.

Beyond the token content itself, we also limit its exposure. Rather than storing the token in a cookie, our client SDK keeps it in the browser's local storage, which is never sent along with HTTP requests. This ensures the token is not inadvertently shared with third parties. To bootstrap the SDK, we generate a lightweight _cpi HTTP-only cookie on the session management subdomain (e.g. cp.example.com) that is not shared with your first-party server.

In accordance with the ePrivacy Regulation, Contentpass only issues tokens for signed-in users. No token is stored on the device of a user who has not signed in.

Checking the subscription state

To check the subscription state, use the authenticate function in our SDK (more information). This function reads the JWT token to determine whether the current user has a valid Contentpass subscription for the current website.

If the token is unavailable (for example, on the first page load after returning from the funnel), has expired, or is about to expire, the Contentpass SDK automatically requests a fresh token using the _cpi cookie.

Server-side usage

Contact our support team to have the full token set as a cookie on your domain. The cookie domain is configurable, typically .example.com.

When the token is set as a cookie on your top-level domain, the user's browser includes it with every request to your servers. This allows you to evaluate the token payload and serve tailored content to Contentpass users.

Token payload

The payload of a token for a signed-in user with a valid subscription for the current site looks like this:

{
  "auth": true,
  "plans": ["ca492af7-320c-42c9-9ba0-b2a33cfca307"],
  "aud": "1234abcd",
  "iat": 1636039699,
  "exp": 1636216099
}

The auth field indicates whether the user is authenticated, plans lists the active subscription plan IDs, aud is your propertyId, and iat/exp are the token's issued-at and expiration timestamps. If the user is signed in but has no active subscription, plans will be an empty array.

Signing algorithm

Contentpass signs tokens using EdDSA (Ed25519), producing compact tokens of approximately 300 bytes. Newly configured properties exclusively use EdDSA. The legacy RS256 algorithm is deprecated and produces larger tokens (~500 bytes). Existing properties may still receive RS256-signed tokens during the transition period.

Validating the token

To ensure a received token is valid, verify the following:

• Token structure: It must be a valid JWT (three Base64-encoded parts separated by dots).
• Signature verification:
  • Use a recommended library from jwt.io/libraries.
  • Verify the signature using the algorithm specified in the alg header (see Signing algorithm above).
  • The OIDC configuration endpoint is at https://my.contentpass.net/.well-known/openid-configuration. The jwks_uri setting points to https://my.contentpass.net/auth/oidc/jwks.
  • If the token header contains a key ID (kid), use the corresponding key from the JWKS. If it does not contain a key ID, try all provided keys.
  • Do not cache the JWKS endpoint response for longer than 1 hour. We typically notify you in advance when keys are rotated, but short-notice changes may occur.
• Payload validation:
  • Verify the auth claim is true.
  • Verify the plans array contains at least one entry.
  • Verify the aud (audience) claim matches your propertyId. Note that mobile apps use different propertyIds than websites.
  • Verify the iat (issued at) timestamp is in the past, allowing a few minutes for clock drift.
  • Do not reject tokens based on the exp claim alone. See Handling expired tokens for details.

Handling expired tokens

Consider this scenario: a user visits example.com, signs in, and receives a valid token that is also set as a cookie. Later, the user returns after the token has expired. The first request arrives at your server with the expired token attached. If your server rejects expired tokens outright, the user gets the experience intended for non-Contentpass users, even though their subscription is still active.

Once the page loads, the Contentpass SDK detects the expired token and refreshes it using the _cpi cookie. Subsequent requests then contain a valid token. However, the initial page load has already delivered a poor experience.

Server-side redirect to refresh token (recommended)

When you detect an expired token that appears otherwise valid (i.e. plans still contains entries), redirect the user to our token refresh endpoint:

https://:sessionManagementSubdomain/auth/login/token/refresh?continue=:continueUrl&property=:propertyId

Parameter	Description
:sessionManagementSubdomain	Your session management subdomain (e.g. cp.example.com)
:continueUrl	URL-encoded redirect destination after token refresh
:propertyId	Your Contentpass propertyId (e.g. 1234abcd)

Example:

https://cp.example.com/auth/login/token/refresh?continue=https%3A%2F%2Fwww.example.com%2Farticle.html&property=1234abcd

After successful token renewal, the user is redirected back to the specified URL with a fresh token cookie. This approach ensures Contentpass users always receive the correct content without manual re-authentication.

Ignoring token expiry

If server-side redirect is not feasible, you can ignore token expiry within a safe grace period and serve the Contentpass experience to users presenting an expired but otherwise valid token.

After page load, the SDK automatically detects expired tokens and refreshes them client-side. Subsequent requests to your server will then contain valid tokens.

Important considerations:

• This approach weakens security, so consider implementing monitoring to detect potential abuse.
• This scenario should only occur for the first direct request in a new session. The SDK handles automatic token refresh for consecutive requests.
• Once the grace period expires, users must re-authenticate.
• Choose a grace period that balances user experience with access control. We recommend keeping grace periods as short as practical to minimize security exposure – but long enough to accommodate typical usage patterns on your property.