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.

Requests that leave out tokenFormat still return a signed JWT. Set tokenFormat to SHORT when an email or SMS tool limits URL length. A short token is 43 characters. The link URL stays the same.

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

Key Concepts and SecurityCopy Anchor Link

• 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. Tokens must have an expiration, the maximum duration allowed is 3 years.

Setup RequirementsCopy Anchor Link

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

1. JWT Authentication SetupCopy Anchor Link

• 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.

2. Email magic link Authentication SetupCopy Anchor Link

A. Sombra Authentication MethodCopy Anchor Link

• 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.

B. Create API KeyCopy Anchor Link

To create an API key, go to Developer Settings → API Keys and create a new API key with the scope Generate Preference Access Tokens.

C. Determine Backend EndpointCopy Anchor Link

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"

Generating a Preference Access LinkCopy Anchor Link

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.

API Call (REST Example)Copy Anchor Link

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": Lifetime of the link, in seconds. Required on every record when tokenFormat is SHORT. The maximum is 3 years. If you leave out expiresIn on a JWT, the token lasts 45 seconds. expiresIn is how long the link can be opened. It is not the length of the session after login.
• "tokenFormat": JWT or SHORT. Leave this field out, or set JWT, to keep the signed token. SHORT returns a 43-character token. Transcend stores the claims and returns only the token.
• "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"
    }
  ]
}

API Call (GraphQL Example)Copy Anchor Link

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

mutation CreatePreferenceAccessTokens(
  $input: CreatePrivacyCenterAccessTokensInput!
) {
  createPrivacyCenterAccessTokens(input: $input) {
    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"
      }
    ]
  }
}

The example above returns a JWT. Add tokenFormat SHORT to return a 43-character token. expiresIn is required on every record.

{
  "input": {
    "tokenFormat": "SHORT",
    "records": [
      {
        "email": "user@example.com",
        "expiresIn": 31536000,
        "scopes": ["preferenceManagement"],
        "subjectType": "customer"
      }
    ]
  }
}

Using the CLICopy Anchor Link

The Transcend CLI comes equipped with a command transcend consent generate-access-tokens that can be used to generate a batch of preference access tokens from a CSV.

Once you install the CLI, you can run a command to bulk generate tokens:

transcend consent generate-access-tokens \
  --auth="$TRANSCEND_API_KEY" \
  --file=./users.csv \
  --duration="1 year" \
  --emailColumnName="Email Address" \
  --subjectType=customer

if using Transcend's US backend:

transcend consent generate-access-tokens \
  --auth="$TRANSCEND_API_KEY" \
  --file=./users.csv \
  --duration="1 year" \
  --emailColumnName="Email Address" \
  --subjectType=customer \
  --transcendUrl=https://api.us.transcend.io

Add --tokenFormat=SHORT to write short tokens. --duration is still sent as expiresIn. The default is JWT.

transcend consent generate-access-tokens \
  --auth="$TRANSCEND_API_KEY" \
  --file=./users.csv \
  --duration="1 year" \
  --emailColumnName="Email Address" \
  --subjectType=customer \
  --tokenFormat=SHORT

This command is very useful when cycling your preference access tokens. Given that tokens expire after some period of time, you will want to periodically export all emails from your marketing tool, re-create the preference access tokens using this command, and then re-upload those tokens back into your marketing tool.

Constructing the Preference Access LinkCopy Anchor Link

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 tells the Privacy Center that the access token was generated using transcend authentication with restricted-scope login. A short token requires this query parameter. A JWT can leave it out.
• 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.

Integrating with Downstream SystemsCopy Anchor Link

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.

User Experience with Preference Access LinksCopy Anchor Link

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: A short link that is unknown, expired, or revoked shows "This link is invalid or has expired." A valid token that is missing the preferenceManagement scope asks the user to verify before they can change preferences.

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

Security ConsiderationsCopy Anchor Link

• 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: Rotating the signing key invalidates JWT links. It does not invalidate short tokens. A short token stays valid until expiresIn. There is no public API to revoke one.
• Frontend Handling: The Privacy Center checks the token before it opens a session. A short link that cannot be opened shows "This link is invalid or has expired."