---
title: "Token-based Authentication User Attribution"
slug: "token-authentication-user-attribution"
updated: 2026-03-23T08:07:17Z
published: 2026-03-23T08:07:17Z
---

> ## Documentation Index
> Fetch the complete documentation index at: https://traceabledocs.document360.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Token-based Authentication User Attribution

The token-based authentication method uses a token to transmit the user ID, role, scope, and other information. When setting up this method, you must specify the conditions for Traceable to extract and transform the JWT token and define the attributes according to your requirements. This authentication method is secure and scalable for user attribution, as it embeds the user's ID, role, and scope in the token, which the server can easily verify.

## What will you learn in this topic?

By the end of this topic, you will be able to:

- Understand how token-based authentication links API requests to authenticated users.
- Learn how to define the authentication scope for your environment and services.
- Learn how to extract and transform the JWT token from requests.
- Learn how to map JWT claims to authentication attributes for user attribution.

---

## Understand token-based authentication user attribution

Token-based authentication user attribution helps you identify who is accessing your APIs by extracting identity claims from JWT or bearer tokens. It connects each request to a verified user and enriches it with contextual information such as role and scope, improving visibility, control, and threat analysis. The table below explains why you use it, when it applies, and how you can leverage it.

| Why use it? | When to use? | How can you leverage it? |
| --- | --- | --- |
| You gain deep visibility into authenticated API activity by extracting identity claims such as user ID, role, and scope directly from JWT tokens. This enables accurate, scalable, and context-rich user attribution without relying on static credentials, improving observability and security insights across your APIs. | You use this when your application relies on JWT or bearer tokens for authentication, and identity claims are available in request headers, body, or cookies. It is especially relevant when you need user-level context for analytics, policy enforcement, or security evaluation across environments and services. | You attribute each API request to a verified user and enrich it with contextual claims to strengthen monitoring, auditing, and compliance. You correlate user roles and privileges with anomalies, detect misuse of access controls, and apply conditions and transformations (such as Regex, Base64 decoding, and JSON Path) to accurately extract, validate, preview, and enforce user attribution rules. |

---

## Steps to configure

To configure token-based authentication, complete the following steps:

#### Step 1 — Define the authentication scope

1. Specify the **Name**.
2. (Optional) Specify a **Description** for the configuration.
3. Select the **Environment** in which you wish to apply the configuration.
4. Select the **Services** on which Traceable should apply the configuration. You can either select all or specific services from the drop-down according to your requirements.
5. (Optional) Specify the **URL Regex** if you wish to provide a granular scope for user attribution.
6. Click **Next**.

![](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/Traceable_user_attribution_token_based_define_scope-window(1).png)

Token-Based Attribution Define Scope Window

#### Step 2 — Define the conditions to extract and transform the JWT token

1. (Optional) Click +**Add Condition**, then select and specify the location, key, operator, and value to use when Traceable checks spans for a match. If a span satisfies the condition, Traceable further evaluates the remaining configurations.
2. Select the **Location** and specify the key where Traceable can find the JWT token. While Traceable specifies this configuration by default using commonly used values, you can modify it to suit your requirements.
3. (Optional) Click **+ Add Value Transformation** to add either of the following custom transformations:

While Traceable pre-adds some default transformations, you can add custom transformations. Traceable evaluates these transformations in order, from top to bottom.

> [!NOTE]
> Note
> 
> You can modify the values, if any, in the pre-added transformations and reorder them according to your requirements.
  - **Regex Capture Group** — This transformation enables you to extract specific parts of a string or value that match the pattern you define.
  - **Base64 Decoder** — This transformation enables you to convert encoded Base64 data back to its decoded or original format.
  - **JSON Path** — This transformation enables you to navigate and select a specific key within a nested JSON structure.
4. Do one of the following according to your requirements:
  - If you use the default values Traceable defines, click **Generate Preview** in the **Preview Attributes** section on the right. This shows the payload and details Traceable extracts from the JWT token. You can also click **View Details** to see the values returned corresponding to each step above.
  - If you modified the values above, click **Reload** in the **Preview Attributes** section on the right. Post-reload, click **Generate Preview** to view the **JWT Token** extracted by Traceable. You can also click **View Details** to see the values returned corresponding to each attribute you configured above.
5. Click **Next**.

![](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/Traceable_user_attribution_token_based_scheme_window(1).png)

User Attribution Token-based Extract Token Step

#### Step 3 — Define the authentication attributes

1. From the list of available attributes, select the one(s) you wish to add. Depending on the attribute you select, complete the following steps:
  - **User ID**/**User Role**/**User Scope**/**Custom**:

Repeat the above steps to add one or more attributes, or complete the steps below to add the Auth Type attribute, according to your requirements.
    1. (Optional) Select the checkbox if you wish to Obfuscate the value post-attribution within the platform.
    2. (For **Custom** only) Specify the **Key** (Attribute Key) you wish to use as part of the authentication process.
    3. (Optional) Click +**Add Condition**, then select and specify the location, key, operator, and value to use when Traceable checks spans for a match.
    4. Specify the **Claim Location in Token**(**JSON Path**) where Traceable can find the attribute.
    5. (Optional) Click **+ Add Value Transformation** to add either of the following custom transformations:

You can also reorder the transformations according to your requirements. Traceable evaluates them in order, from top to bottom.
      - **Regex Capture Group** — This transformation enables you to extract specific parts of a string or value that match the pattern you define.
      - **Base64 Decoder** — This transformation enables you to convert encoded Base64 data back to its decoded or original format.
      - **JSON Path** — This transformation enables you to navigate and select a specific key within a nested JSON structure.
  - **Auth Type**—****You can select the authentication type from the drop-down list according to your requirements. You can also create a new one according to your requirements.
2. Generate the preview of the attribute value(s) by doing one of the following:
  - If you use the default values Traceable defines, click **Generate Preview** in the **Preview Attributes** section on the right. This shows the details generated in Step 2 above, and the value(s) extracted for the attributes. You can also click **View Details** to see the values returned corresponding to each attribute above.
  - If you modified the values above, click **Reload** in the **Preview Attributes** section on the right. Post-reload, click **Generate Preview** to view the details generated in Step 2 above, and the value(s) extracted for the attributes. You can also click **View Details** to see the values returned corresponding to each attribute you configured above.
3. Click **Submit**.

---

## Examples and Demo

The following examples demonstrate how Traceable performs user attribution by extracting user identity claims from JWT tokens present in API requests:

****Example 1 — When a JWT token is sent in the Request Header of an API****

In this scenario, you must add Transformations to extract the JWT token from the header and decode it. Then, you can select the attributes you wish to identify. For example, if you consider the following JWT token and its corresponding payload for the demo, and the `email` claim in the payload contains the user ID. To extract it, you must add a *Regex Capture Group* transformation as shown in the below demo. Then, upon execution, Traceable extracts `random` as the user ID.

| JWT Token | Payload |
| --- | --- |
| `authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoicmFuZG9tIiwiZW1haWwiOiJyYW5kb21AdHh0LmNvbSIsInN1YiI6ImRlbW9BcHBVc2VyIiwiaXNzIjoiZGVtby1zZXJ2ZXIiLCJqdGkiOiI5ODc2NTRiMS0yMzRiLTU2NzgtYjJkNC1kNDA1YzEyMzQ1YWIiLCJhdWQiOiJkZW1vLWFwcC11c2VycyIsIm5iZiI6MTczODY0NDExNX0.zv45yfr2nK8geZeMiEvePT-NA4JG1p16VmYczmdC8A0` > [!NOTE] > Note > > The above JWT token is for reference purposes only. | ```plaintext { "name": "random", "email": "random@txt.com", "sub": "demoAppUser", "iss": "demo-server", "jti": "987654b1-234b-5678-b2d4-d405c12345ab", "aud": "demo-app-users", "nbf": 1738644115 } ``` |

****Example 2**—**When a JWT token is sent in the Request Body of an API****

In this scenario, you must add Transformations to extract the JWT token from the body and decode it. Then, you can select the attributes you wish to identify. For example, if you consider the following JWT token and its corresponding payload, then upon execution, Traceable extracts `johndoe.com` and `Administrator` as the user ID and role, respectively. Further, Traceable obfuscates these values on the platform.

| JWT Token | Payload |
| --- | --- |
| `"jwt": "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE3MzA5MTM0MzcsImV4cCI6MTc2MjQ0OTQzNywiYXVkIjoid3d3LnRyYWNlYWJsZS5haSIsInVzZXItaWQiOiJqb2huZG9lLmNvbSIsIkdpdmVuTmFtZSI6IkpvaG4iLCJTdXJuYW1lIjoiRG9lIiwiRW1haWwiOiJqZG9lQHRyYWNlYWJsZS5haSIsInJvbGUiOiJBZG1pbmlzdHJhdG9yIn0.YJoUiIQnEpANAJEuyQdpdwHzEOCr68xOjRvOYfcjHII"` > [!NOTE] > Note > > The above JWT token is for reference purposes only. | ```plaintext { "iat": 1730913437, "exp": 1762449437, "aud": "www.traceable.ai", "user-id": "johndoe.com", "GivenName": "John", "Surname": "Doe", "Email": "jdoe@traceable.ai", "role": "Administrator" } ``` |

****Example 3**—**When a JWT token is sent in the Request Cookie of an API****

In this scenario, you must remove existing Transformations to extract the JWT token from the cookie and attribute it. Then, you can select the attributes you wish to identify. For example, if you consider the following JWT token and its corresponding payload, then upon execution, Traceable extracts `john.doe` as the user ID. Further, Traceable obfuscates these values on the platform.

| JWT Token | Payload |
| --- | --- |
| `jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJqb2huLmRvZSIsIm5hbWUiOiJKb2huIERvZSIsImlhdCI6MTIzNDU2Nzg5MCwiZ2l2ZW5fbmFtZSI6IkpvaG4iLCJmYW1pbHlfbmFtZSI6IkRvZSIsInVwZGF0ZWRfYXQiOiIyMDIzLTExLTEwVDE1OjE0OjAzLjY3MFoiLCJlbWFpbCI6ImpvaG4uZG9lQHRyYWNlYWJsZS5haSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJleHAiOjEyMzQ1Njc4OTAsInNpZCI6Ill6ei1qNWFiY2RlZmc5ajktYWJjZGVmZ2hpamsxamN6In0.-6zDczoEfNhKXyW85460oGXFvRtKwLyRuxaPx53FEDA` > [!NOTE] > Note > > The above JWT token is for reference purposes only. | ```plaintext { "name": "John Doe", "iat": 1516239022, "given_name": "John", "family_name": "Doe", "sub": "john.doe", "updated_at": "2023-11-10T15:14:03.670Z", "email": "john.doe@traceable.ai", "email_verified": true, "iat": 1234567890, "exp": 1234567890, "sid": "Yzz-j5abcdefg9j9-abcdefghijk1jcz" } ``` |

****Demo****

The following interactive demo walks you through the steps to configure token-based user attribution:

[Embedded content](https://demo.arcade.software/CF1OInwKH17lradByXI0)

Obfuscate means alteration of sensitive data in a way that it conceals its original value while retaining a format that is valid or similar to the original. This enables data usage for analysis and testing without exposing the original value.