Preference Access Links

Preference Access Links, often referred to as "magic links," provide a personalized, one-step approach for users to access and manage their consent preferences. When a user clicks a Preference Access Link, they are taken directly to their individual preference center, with their current preferences pre-populated. This streamlined experience eliminates the need for manual login or multiple verification steps, offering a "one-click" journey to manage consent.

This approach:

  • Enhances user experience by simplifying the Preference Management process
  • Increases engagement and compliance by making it easier for users to update their choices
  • Provides a direct and personalized route to consent settings for both account holders and non-account holders

When you implement Preference Access Links with Transcend, the process works by generating a unique, time-limited token for each user. This token is embedded into a URL, which can then be distributed via email or other communication channels. When the user clicks the link, the token authenticates their session, allowing them to view and modify their preferences directly.

This guide will walk you through implementing Preference Access Links for preference changes using the Transcend API.

  • Restricted Scope:
    Preference Access Link tokens can be restricted in scope. You can configure these tokens to include scopes to DSR Automation, Preference Management, or other functionalities.
  • Token Validation:
    When a user accesses the Privacy Center with a Preference Access Link, the backend and Sombra™ service validate the token and its scope. If the token does not have the required scope, access is denied and the user is redirected to the login page.
  • Token Expiry:
    For most use cases, short-lived tokens (e.g., 1 hour) are recommended for security. However, for marketing automation tools that require links to remain valid indefinitely, you can generate long-lived tokens. Be aware of the security trade-offs when using long-lived tokens.

Before implementing Preference Access Links, you'll need to gather these key values:

  • If you are already using JWT authentication as listed in the JWT Account Login, ensure that the JWT is signed with the correct scopes.
  • For Preference Access Links, the JWT should include the preferenceManagement scope to allow users to manage their preferences.
  • No additional setup is required if you are already using JWT authentication for your Privacy Center.
  • Make sure DATA_SUBJECT_AUTHENTICATION_METHODS and EMPLOYEE_AUTHENTICATION_METHODS environment variables are set to include transcend as an authentication method.
  • This ensures that Sombra can authenticate users via Transcend signed JWT Tokens.

To create an API key, go to Developer Settings → API Keys and create a new API key with the scope Modify User Stored Preferences.

Note: Once created, you will only have one opportunity to save this API key. Please store the API key securely.

To determine which API endpoint you should use:

  1. If your organization is hosted in the US infra, the backend URL is: 
    TRANSCEND_BACKEND_URL="https://api.us.transcend.io"
  2. If your Transcend instance is hosted in the EU infra,the backend URL is : 
    TRANSCEND_BACKEND_URL="https://api.transcend.io"

To generate a Preference Access Link, you will use the Transcend API to create a unique token tied to a specific user identifier. This token will then be appended to your Privacy Center URL.

The createPrivacyCenterAccessTokens graphQL mutation can be used to generate a Preference Access Link token.

TRANSCEND_BACKEND_URL="https://api.transcend.io"
TRANSCEND_US_BACKEND_URL="https://api.us.transcend.io"
TRANSCEND_API_KEY="YOUR_API_KEY"

curl --location "${TRANSCEND_BACKEND_URL}/graphql" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $TRANSCEND_API_KEY" \
--data-raw '{"query":"mutation CreatePrivacyCenterAccessTokens($input: CreatePrivacyCenterAccessTokensInput!) {\n  createPrivacyCenterAccessTokens(input: $input) {\n    nodes {\n      token\n    }\n  }\n}","variables":{"input":{"records":[{"email":"user@example.io","expiresIn":3600,"scopes":["preferenceManagement"],"subjectType":"customer"}]}}}'

In this request:

  • "email": This is the email address of the user for whom you are generating the Preference Access Link.
  • "coreIdentifier": (Optional) If you are using a core identifier for your users, you can include it here.
  • "expiresIn": This defines the lifespan of the token in seconds. Use a longer expiry (e.g., 1 year) for marketing tools that require persistent links.
  • "scopes": This should include preferenceManagement to allow the user to manage their preferences. The set of available scopes include preferenceManagement, dsrAutomation.
  • "subjectType": This should be set to the data subject type defined on your organization's Admin Dashboard (e.g., customer, employee).

A successful response will return nodes containing token that you can use to construct the Preference Access Link:

{
  "nodes": [
    {
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZGVudGlmaWVycyI6eyJlbWFpbCI6InVzZXJAZXhhbXBsZS5jb20ifSwidHlwZSI6IlBSSVZBQ1lfQ0VOVEVSX0FDQ0VTUyIsInNjb3BlcyI6WyJwcmVmZXJlbmNlTWFuYWdlbWVudCJdLCJleHBpcmVzSW5TZWNvbmRzIjozNjAwLCJpYXQiOjE2Nzg4ODY0MDAsImV4cCI6MTY3ODg4OTk5OX0.signature"
    }
  ]
}

You can also generate tokens in batch using the GraphQL mutation createPrivacyCenterAccessLinks:

mutation CreatePreferenceAccessLinks($request: [CreateAccessLinkInput!]!) {
  createPrivacyCenterAccessLinks(request: $request) {
    nodes {
      token
    }
  }
}

Example input:

{
  "input": {
    "records": [
      {
        "email": "user@example.com",
        "coreIdentifier": "user-12345", // Optional, if you utilize core identifier
        "expiresIn": 31536000, // 1 year in seconds
        "scopes": ["preferenceManagement"],
        "subjectType": "customer"
      }
    ]
  }
}

Once you have the token, you can construct the full Preference Access Link by appending it as a query parameter to your Privacy Center URL.

Your Privacy Center URL can be found in your Transcend Admin Dashboard under Privacy Center → General Settings.

For example, if your Privacy Center URL is https://privacy.example.com and your token is YOUR_ACCESS_TOKEN, the Preference Access Link would be:

https://privacy.example.com/login?tokenType=access-link#YOUR_ACCESS_TOKEN
  • The tokenType=access-link query parameter signals to the Privacy Center that the access token was generation using transcend authentication with restricted-scope login. This query parementer isn't required if the token is generated using JWT authentication.
  • The token itself is passed in the URL fragment (#), which is not sent to the server by browsers, providing an extra layer of privacy.

This link can then be embedded in your emails, SMS messages, or other communication channels.

To fully leverage Preference Access Links, you'll typically integrate the token generation process with your marketing automation platforms (e.g., Customer.io, Marketo) or other systems that send user communications.

The general workflow is as follows:

  1. User Data Creation/Update: When a user's data is created or updated in your system (e.g., when they sign up for a newsletter or make a purchase), trigger a call to Transcend to generate a Preference Access Token for that user.
  2. Store the Token: Store the generated token alongside the user's profile in your downstream system. You might use a custom field for this purpose (e.g., transcend_magic_link_token).
  3. Embed in Communications: When sending emails or other communications, dynamically insert the stored token into the Preference Access Link URL.
  4. Filter Campaigns (Optional): Some systems allow you to filter campaigns or send communications only to users for whom a Preference Access Token has been successfully generated. This ensures that the "one-click" experience is consistent for all recipients.

By automating this process, you can ensure that every user receives a personalized and convenient link to manage their preferences.

When a user clicks a Preference Access Link:

  • Direct Access: They are immediately redirected to your Privacy Center.
  • Pre-populated Preferences: Their current consent preferences (e.g., for marketing, analytics, etc.) will be automatically displayed, allowing them to see their current choices at a glance.
  • Simplified Management: They can then easily modify their preferences and save their changes without needing to log in or undergo additional verification steps.
  • Scope Enforcement: If the token does not have the required scope (e.g., if it is expired or does not allow Preference Management), the user will be redirected to the login page and shown an appropriate message.

This seamless experience greatly improves the user's ability to exercise their data rights and promotes a higher level of trust and transparency.

  • Token Scope: Always use the minimum required scope for your use case. For Preference Access Links, use preferenceManagement only.
  • Token Expiry: Use short-lived tokens when possible. For marketing tools that require persistent links, use long-lived tokens but monitor for misuse.
  • Revocation: If a token is compromised, you can rotate the signing key or update user identifiers to invalidate old tokens.
  • Frontend Handling: The Privacy Center will check the token's scope and expiry. If the user does not have sufficient permissions, they will be redirected to the login page.