Signed token

When someone visits your application, we need a way to recognize them and provide personalized experiences. Think of a token as a digital ID card that helps us identify each visitor and ensure their data stays safe.

By default, every visitor gets a unique anonymous ID that's stored in their browser. This ID is included in a token that travels with every request they make. This token helps us know it's the same person visiting your application.

How tokens work

There are two types of tokens you can use in your application:

Unsigned tokens

These are the standard tokens that work great for anonymous visitors. They are automatically generated and stored in the visitor's browser, so there is no setup required on your end.

Signed tokens

These tokens add an extra layer of verification. Your application creates the token and signs it using your API key, like adding an official stamp to the ID card. This helps us confirm that the information in the token is authentic and hasn't been tampered with.

Here is how the process works:

Why use signed tokens

Signed tokens minimize the risk of impersonation attacks when dealing with identified users. An impersonation attack is when someone pretends to be another user to gain access to their personalized content or data.

Imagine if someone could create a fake ID card with another person's name on it. That is what could happen without signed tokens: someone could potentially modify their token to pretend to be a different user.

The risk level depends heavily on how you identify users:

• Guessable IDs (higher risk): Email addresses, usernames, sequential numbers, or social security numbers are predictable. Someone could potentially guess or discover another user's ID and modify their token to impersonate them.

• Cryptographically Random IDs (lower risk): If you use randomly generated IDs like 7f9a3c2e-8d1b-4f5a-9e2c-1b8d4e6f3a7c, impersonation becomes much harder. An attacker could not simply guess the ID, they would need to somehow access the victim's browser cookies or other storage where your application keeps this information.

Even with random IDs, signed tokens add an extra layer of protection and ensure token integrity, which is why we recommend them for identified users regardless of your ID format.

Impersonation explained

Consider a scenario where you identify users by email address, such as alice@example.com.

Without signed tokens, there's a potential vulnerability:

• Modified browser requests could claim to be from alice@example.com
• This could expose Alice's personalized content
• Actions could be triggered under Alice's identity

Using random IDs (instead of email addresses) adds a layer of difficulty since discovering a specific random ID is challenging, but does not fully solve the problem.

With signed tokens, you get robust protection:

1. Your application creates a token containing Alice's information
2. The token is signed using your secret API key
3. Our servers verify the signature
4. Any attempt to modify the token invalidates the signature
5. Requests with invalid signatures are automatically rejected

This cryptographic verification ensures secure authentication regardless of your ID strategy, whether you use email addresses, sequential numbers, or random identifiers.

How to enforce signed tokens

Follow these steps to require signed tokens for your application:

1. Go to the Application settings.

2. Scroll down to the Security section.

3. Enable the Require signed token toggle to enforce signed tokens.

Although not recommended, you can disable signed tokens at any time by following the same steps and turning the toggle off. When disabled, both signed and unsigned tokens will be accepted to allow a smooth transition.