ABAC JWT migration guide
26.3.0.cl
Cloud (Latest)

ABAC JWT migration guide

Administrators can migrate their existing implementation of ABAC with JSON Web Token (JWT) to the new ABAC via RLS model, where:

  • Row-level security (RLS) rules are defined in ThoughtSpot on tables and data models

  • JWTs only provide values for variables used in those RLS rules, instead of sending full filter rules.

Supported migration paths🔗

Important notes and considerations🔗

Review the information in the following sections before getting started with the migration.

ABAC feature support🔗

The legacy JWT ABAC implementation is deprecated and will be removed from the product in an upcoming version. The ABAC beta implementation is no longer supported in ThoughtSpot. ThoughtSpot strongly recommends using ABAC via RLS in all new implementations and migrating your existing legacy or beta JWT ABAC implementation to ABAC via RLS.

Persistence behavior🔗

ABAC via RLS does not support session-based ABAC rules ("persist_option": "NONE"). If your implementation currently relies on session-based rules:

  • Create dedicated user accounts for your application users. You can use REST APIs to automate user creation, update, or deletion.

  • Apply persisted security rules to those users.

  • Use cookieless authentication with these persisted users.

This approach addresses all use cases that previously relied on session-based JWT and ensures Liveboard schedule attachments enforce security rules and deliver only secured output to your end users.

Table joins🔗

The filters in JWT ABAC beta implementation respect MODEL JOINS. However, RLS by default is an INNER join. If you want to adjust behavior for your implementation, contact ThoughtSpot Support.

From legacy JWT ABAC with filter_rules to ABAC via RLS🔗

Before migrating to the new method, complete the following checks:

  • Analyze your current JWT ABAC implementation.

  • Configure equivalent RLS rules using variables.

  • Implement and test RLS-based ABAC in a non-production environment.

  • Adjust your JWT payloads to set variable values instead of filter_rules.

  • Roll out and decommission legacy JWT ABAC.

Analyze your current implementation🔗

In a typical legacy JWT ABAC implementation:

  • The /api/rest/2.0/auth/token/custom endpoint is used for JWT generation, populating filter_rules or parameter_values in the token to create data security rules. Depending on user requirements, these values are applied on all models or specific models as per the object scope set in the request payload.

    curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/auth/token/custom'  \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "username": "secured_user",
  "secret_key": "{secret_key}",
  "persist_option": "REPLACE",
  "filter_rules": [
   {
     "column_name": "Country",
     "operator": "IN",
     "values": ["Germany", "Australia"]
   }
  ]
}'

  • The is_mandatory_token_filter attribute is set to true on columns in Models to secure them by default.

    Mandatory token filter

  • Indexing on all sensitive columns in your Tables is disabled.

Retrieve values from user properties (Optional)🔗

If required, you can retrieve the filter and parameter values stored for each JWT user from the user metadata via a POST request to the /api/rest/2.0/users/search API endpoint. The access_control_properties section of user metadata returned in the API response includes this information:

[{
	"id": "0000084b-1e75-d506-8258-0b6abbb863ed",
	"name": "testjwtuser",
	"display_name": "testjwtuser",
	[...]
	"access_control_properties": {
		"<org_id>": {
			"ALL": {
				"filter_rules": [{
					"column_name": "country",
					"operator": "IN",
					"values": ["Germany", "Australia"]
				}],
				"parameter_values": []
			}
		}
	},
	"variable_values": {}
}]

Configure equivalent RLS rules and variables🔗

You may want to set up RLS rules and variables equivalent to filter and parameter rules in your existing implementation. Note that the following mapping pattern applies to each attribute:

  • Column in filter_rules → RLS rule condition with formula variable on that column.

  • Values in filter_rules → variable values passed via JWT.

  • is_mandatory_token_filter behavior → RLS rule that denies all when variable is empty or missing.

  • TS_WILDCARD_ALL or similar “allow all” semantics → variable value TS_WILDCARD_ALL in the RLS rule.

To set equivalent RLS rule conditions and variables:

  1. Create formula variables using the /api/rest/2.0/template/variables/create API endpoint. These variables will be referenced in RLS rules. To create variables, you need ADMINISTRATION (Can administer ThoughtSpot) privilege. If role-based access control (RBAC) is enabled on your instance, the CAN_MANAGE_VARIABLES (Can manage variables) privilege is required.

  2. Create rules using these variable(s) directly on the ThoughtSpot table in the Row Security Editor tab. These should be the same rules as the ones previously defined in the JWT, which will be ultimately replaced after migration. To add multiple conditions, use the AND operator.

    RLS rules editor

  3. Create a JWT token request with variable_values and generate the token using the /api/rest/2.0/auth/token/custom API endpoint. Note that these values can be scoped to specific models, so that different security rules can be applied to different data in ThoughtSpot.

    curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/auth/token/custom'  \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "username": "secured_user",
  "secret_key": "{secret_key}",
  "persist_option": "REPLACE",
  "variable_values": [
    {
      "name": "country_rls_var",
      "values": [
        "Germany",
        "Australia"
      ]
    },
    {
      "name": "category_rls_var",
      "values": [
        "Jeans",
        "Jackets"
      ]
    }
  ],
  "objects": [
    {
      "type": "LOGICAL_TABLE",
      "identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca"
    },
    {
      "type": "LOGICAL_TABLE",
      "identifier": "38399c50-02f1-4310-804b-214b81f25333"
    }
 ]}'

  4. Keep indexing disabled on all sensitive columns

    Note
    		 Users with administration and Can Administer and Bypass RLS privileges are exempt from RLS rules and can view all rows unless additional logic is implemented to secure rows in the data model. RLS rules are defined on tables, but Models can be configured to either apply or bypass those rules. For more information, see How RLS rules work.

  5. Verify variable values are assigned to your users. This information can be retrieved using one of the following methods:

    • Via a POST request to the /api/rest/2.0/users/search API endpoint. Verify the variable_values section of the user metadata returned in the API response.

    • Via a POST request to the /api/rest/2.0/template/variables/search API endpoint, with variables specified in the request body. Set response_content to METADATA_AND_VALUES to fetch the variable values and verify the response payload.

      Note

      We do not recommend using the /api/rest/2.0/users/{user_identifier}/update endpoint to update variable values for a user. Instead, use either /api/rest/2.0/template/variables/update-values or /api/rest/2.0/auth/token/custom.

Expected setup before the testing phase🔗

Ensure that you have both legacy JWT GA and ABAC via RLS properly set up in your environment before starting the tests. For testing purposes, we’ll use an example setup with filter_rules, the mandatory token filter setting in the model, and RLS rules with country_rls_var and category_rls_var variables.

Your implementation can also include parameters to configure security rules by using pass-through functions. Typically, users may want to map existing security rules, such as those created with filter_rules or parameter values used in model formulas and model filters, to new RLS rules that reference variables and are applied at the table level.

Test the migration🔗

We recommend testing the migration in these main steps:

  • Ensure everything continues to work correctly when both legacy JWT GA and ABAC via RLS are enabled.

  • Remove filter conditions on legacy JWT ABAC implementation to test how security rules function with solely ABAC via RLS.

  • Remove legacy JWT GA, and retain only ABAC via RLS.

Important

When creating a token request with "persist_option": "REPLACE", the presence (or absence) of specific keys in your JSON payload determines whether existing security rules are retained, updated, or deleted.

Legacy rules🔗

The legacy parameters, filter_rules and parameter_values, are linked. If you define one without including the other in the API request, the omitted parameter will be deleted from the user profile. This behavior remains unchanged with the introduction of variable_values to maintain backward compatibility.

Migration to variable_values🔗

The variable_values parameter in the ABAC via RLS implementation operates independently. Sending variable_values alone will not erase your legacy rules. Likewise, sending legacy parameters without variable_values will not erase stored variable values.

This allows developers to assign variable_values for ABAC via RLS without disrupting an existing legacy JWT GA setup. To reset all legacy values from users' metadata, use "persist_option": "RESET".

Summary matrix🔗

Use the information in the following table to understand how API calls change the user’s stored security settings and variable store settings:

Your payload includes…​filter_rules in user’s access_control_propertiesparameter_values in user’s access_control_propertiesvariable_values in the variable store

Legacy requests

Both filter_rules and parameter_values

Updates

Updates

Unchanged

Only filter_rules

Updates

DELETED

Unchanged

Only parameter_values

DELETED

Updates

Unchanged

Migration calls

filter_rules and variable_values

Updates

DELETED

Updates

parameter_values and variable_values

DELETED

Updates

Updates

filter_rules, parameter_values, and variable_values

Updates

Updates

Updates

ABAC via RLS only

Only variable_values

Unchanged

Unchanged

Updates

Phase 1: Test RLS while legacy JWT configuration is still enabled🔗

Generate tokens that include both:

  • Your existing legacy JWT ABAC keys (filter_rules and/or parameter_values)

  • New variable_values for your RLS rules

For example:

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/auth/token/custom'  \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "username": "secured_user",
  "secret_key": "{secret_key}",
  "persist_option": "REPLACE",
  "filter_rules": [
   {
     "column_name": "Country",
     "operator": "IN",
     "values": ["Germany", "Australia"]
   }
  ],
  "variable_values": [
    {
      "name": "country_rls_var",
      "values": [
        "Germany",
        "Australia"
      ]
    }
  ]
}'

Since both conditions are similar, the data should be filtered uniformly as shown in the following diagram. If the filtering conditions differ, the resulting data should be the intersection of the two.

JWT migration test

Phase 2: Bypass legacy JWT configuration🔗

If the phase 1 testing is conclusive, bypass legacy JWT configuration. To test RLS independently while keeping legacy JWT configuration as a fallback:

  1. When generating tokens, set the legacy JWT ABAC implementation to allow everything by using the keyword TS_WILDCARD_ALL in your legacy filter_rules and parameter_values.

  2. Keep sending variable_values for the RLS rules as before.

For example:

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/auth/token/custom'  \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "username": "secured_user",
  "secret_key": "{secret_key}",
  "persist_option": "REPLACE",
  "filter_rules": [
   {
     "column_name": "Country",
     "operator": "IN",
     "values": ["TS_WILDCARD_ALL"]
   }
  ],
  "variable_values": [
    {
      "name": "country_rls_var",
      "values": [
        "Germany",
        "Australia"
      ]
    }
  ]
}'

After this configuration, all filtering is governed by the variable rules set for ABAC via RLS, since legacy JWT implementation with filter_rules allows all values.

JWT migration test phase 2

Phase 3: Remove all legacy JWT rules🔗

After the legacy JWT configuration values are set to allow all values for that user, subsequent calls can be made without setting the legacy JWT ABAC values. This allows you to test the payload with variable_values, which you ultimately will be using to generate authentication tokens in the future.

For example:

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/auth/token/custom'  \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "username": "secured_user",
  "secret_key": "{secret_key}",
  "persist_option": "APPEND",
  "variable_values": [
    {
      "name": "country_rls_var",
      "values": [
        "Germany",
        "Australia"
      ]
    }
  ]
}'

For those users:

  • Legacy JWT ABAC GA rules are no longer in effect.

  • Their access is governed solely by ABAC via RLS.

  • This payload should match what you plan to use in production.

JWT migration test phase 3

Examples for mapping legacy JWT ABAC GA expressions to ABAC via RLS🔗

A few examples of how to translate legacy JWT expressions into equivalent RLS rules are listed here. These examples assume the following:

  • Your setup has a variable named country_rls_var.

  • RLS expressions use ts_var(country_rls_var) to reference the value passed via variable_values.

OperatorLegacy JWT ABAC implementationEquivalent values in RLS rules in table for ABAC via RLS

EQ (equal)

"filter_rules": [
  {
    "column_name": "country",
    "operator": "EQ",
    "values": ["germany"]
  }
]

country = ts_var(country_rls_var)

IN (in)

"filter_rules": [
  {
    "column_name": "country",
    "operator": "IN",
    "values": ["germany","australia"]
  }
]

country = ts_var(country_rls_var) (multi-value variable)

NE (not equal)

"filter_rules": [
  {
    "column_name": "country",
    "operator": "NE",
    "values": ["germany"]
  }
]

country != ts_var(country_rls_var)

NOT_IN (not in)

"filter_rules": [
  {
    "column_name": "country",
    "operator": "NOT_IN",
    "values": ["germany","australia"]
  }
]

country != ts_var(country_rls_var) (multi-value variable)

Note

RLS rules support multi-value variables; use appropriate functions or operators in the RLS expression depending on how you want to handle lists.

From JWT ABAC Beta implementation to ABAC via RLS🔗

In this migration scenario, the JWT ABAC beta implementation will be migrated to ABAC via RLS.

Scope and prerequisites🔗

This document assumes that you are currently using the /api/rest/2.0/auth/token/full or /api/rest/2.0/auth/token/object for ABAC token generation, and provides instructions to migrate your ABAC implementation to the /api/rest/2.0/auth/token/custom API endpoint. These migration steps apply only if:

  • Your implementation has used the legacy method of generating JWT tokens via /api/rest/2.0/auth/token/full or /api/rest/2.0/auth/token/object API endpoint.

  • Your instance has the necessary configuration settings enabled for migrating JWT token generation process from the /api/rest/2.0/auth/token/full to the /api/rest/2.0/auth/token/custom API endpoint. For more information, refer to the JWT ABAC beta migration guide.

Important

The legacy JWT ABAC beta implementation is deprecated and is no longer supported in ThoughtSpot.

Review your legacy JWT ABAC Beta implementation🔗

A typical JWT ABAC Beta implementation includes the following:

  1. JWT generation via POST /api/rest/2.0/auth/token/full, with runtime_filters and other attributes populated for creating data security rules. Depending on user requirements, the values are set on all models or for specific models.

    curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/auth/token/full'  \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "username": "secured_user",
  "secret_key": "{secret_key}",
  "user_parameters": {
    "runtime_filters": [
      {
        "column_name": "Country",
        "operator": "IN",
        "values": ["Germany", "Australia"],
        "persist": true
      }
    ],
    "parameters": [
      {
        "name": "Secured",
        "values": ["f65fee3a-75f4-4e6e-a801-995113566d68"],
        "persist": true
      }
    ],
  }
}'

You may also be using a parameter property to pass a validation in the data model and ensure that the model is secured by default, as shown in the following token request example:

JWT beta migration test

Ensure that indexing is disabled on all sensitive columns in your tables.

Retrieve values stored for each user (Optional)🔗

If required, you can retrieve the values previously stored for each user after token generation. To do so, get user metadata via the /api/rest/2.0/users/search API endpoint. The response from this call provides a list of filter and variable values in the user_parameters section of the output.

For example:

[{
	"id": "0000084b-1e75-d506-8258-0b6abbb863ed",
	"name": "testjwtuser",
	"display_name": "testjwtuser",
	[...]
	"user_parameters": {
		"<org_id>": {
          "runtimeFilters": [{
            "columnName": "Country",
			"operator": "IN",
			"values": ["Germany", "Australia"]
          }],
        }
	},
	"variable_values": {}
}]

This can be helpful when you design equivalent ABAC via RLS rules and want to validate that the same logic will be enforced.

Set up ABAC via RLS🔗

Configure ABAC via RLS while keeping the legacy Beta JWT ABAC in place.

  1. Create variables, with their type as FORMULA_VARIABLE using the /api/rest/2.0/template/variables/create API endpoint. These variables will be referenced in your RLS security rules.

  2. Create RLS rules on tables and reference these variables in the rules.

    RLS rules

  3. Where applicable, replicate your existing JWT ABAC Beta logic. To add more than one condition, you can use the AND operator.

  4. To assign values to these variables, define the variable_values in your token generation request to /api/rest/2.0/auth/token/custom API endpoint. These attributes will ultimately replace conditions defined via runtime_filters in your current JWT ABAC beta implementation.

    Note

    The variable values can be scoped to specific models, so that different security rules can be applied to different data sets in ThoughtSpot.

    curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/auth/token/custom'  \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "username": "secured_user",
  "secret_key": "{secret_key}",
  "persist_option": "REPLACE",
  "variable_values": [
    {
      "name": "country_rls_var",
      "values": [
        "Germany",
        "Australia"
      ]
    },
    {
      "name": "category_rls_var",
      "values": [
        "Jeans",
        "Jackets"
      ]
    }
  ],
  "objects": [
    {
      "type": "LOGICAL_TABLE",
      "identifier": "model1-guid"
    },
    {
      "type": "LOGICAL_TABLE",
      "identifier": "model2-guid"
    }
  ]
}'

  5. Keep indexing disabled on all sensitive columns.

Note

  • RLS can be turned on or off per model created from a table. When enabled on a model, its queries honor the table’s RLS rules; when disabled, users see all data allowed by table-level RLS.

  • ThoughtSpot administrators are exempt from RLS by default. For more information, see How rule-based RLS works.

Verify variable values for users (Optional)🔗

Verify that variable values are correctly assigned to users using one of the following methods:

  • Send a POST request to the /api/rest/2.0/users/search with user details, and explore the variable_values section of the response payload.

  • Send a POST request to the /api/rest/2.0/template/variables/search API endpoint with variable details. In the request body, specify the response_content as METADATA_AND_VALUES, and explore the variable values for each user in the response payload.

If you want to update variables, use either /api/rest/2.0/template/variables/update-values or /api/rest/2.0/auth/token/custom API endpoint.

Review the configuration🔗

Before you begin testing, your setup should have the following JWT ABAC configuration:

  • Your JWT ABAC beta implementation has tokens generated for your users via POST /api/rest/2.0/auth/token/full, with runtime_filters and required parameters.

  • Variables are configured, RLS rules with variables are applied on the tables, and the values for variables are defined in the tokens generated via /api/rest/2.0/auth/token/custom API endpoint.

Test the migration🔗

We recommend testing the migration in three stages:

  1. Verify user entitlements when both ABAC via RLS and JWT ABAC Beta tokens are enabled.

  2. Remove filtering conditions on legacy JWT Beta tokens to test how security rules function with solely ABAC via RLS.

  3. Remove legacy JWT Beta and verify the ABAC via RLS.

Phase 1: ABAC via RLS while JWT ABAC Beta token is still active🔗

In this step, create the following token requests:

  • Set security rules for JWT Beta using POST /api/rest/2.0/auth/token/full API endpoint. For example:

    curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/auth/token/full'  \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "username": "secured_user",
  "secret_key": "{secret_key}",
  "user_parameters": {
    "runtime_filters": [
      {
        "column_name": "Country",
        "operator": "IN",
        "values": ["Germany", "Australia"],
        "persist": true
      }
    ],
    "parameters": [
      {
        "name": "Secured",
        "values": ["f65fee3a-75f4-4e6e-a801-995113566d68"],
        "persist": true
      }
    ],
  }
}'

  • Set variable values for ABAC via RLS using POST /api/rest/2.0/auth/token/custom API endpoint. For example:

    curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/auth/token/custom'  \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "username": "secured_user",
  "secret_key": "{secret_key}",
  "persist_option": "REPLACE",
  "variable_values": [
    {
      "name": "country_rls_var",
      "values": [
        "Germany",
        "Australia"
      ]
    }
  ],
}'

Since both conditions are similar, the data should be filtered uniformly as illustrated in the following diagram. If the filtering conditions differ, the resulting data should be the intersection of the two.

JWT beta migration 1

Phase 2: Bypass JWT ABAC Beta attributes🔗

If the test above is conclusive, the next step is to test bypassing legacy JWT Beta attributes. To achieve this:

  1. Remove all conditions for filters and leave parameters unchanged.

    curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/auth/token/full'  \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "username": "secured_user",
  "secret_key": "{secret_key}",
  "user_parameters": {
    "runtime_filters": [
    ],
    "parameters": [
      {
        "name": "Secured",
        "values": ["f65fee3a-75f4-4e6e-a801-995113566d68"],
        "persist": true
      }
    ],
  }
}'

  2. Verify that your users no longer have runtime_filters values by calling the POST /api/rest/2.0/users/search API. The user property must show an empty user_parameters.runtimeFilters property.

  3. With your user no longer having filtering conditions applied via JWT ABAC Beta, create a login token passing security rules using POST /api/rest/2.0/auth/token/custom API endpoint to implement ABAC via RLS.

    curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/auth/token/custom'  \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "username": "secured_user",
  "secret_key": "{secret_key}",
  "persist_option": "REPLACE",
  "variable_values": [
    {
      "name": "country_rls_var",
      "values": [
        "Germany",
        "Australia"
      ]
    }
  ],
}'

In this configuration, filtering rules will only follow ABAC via RLS rules defined via variable_values, because the legacy JWT Beta token doesn’t include any specific filter conditions and allows all.

JWT beta migration test 2

Phase 3: Remove all JWT ABAC beta configuration🔗

After you have validated behavior with JWT ABAC Beta attributes bypassed, remove the legacy JWT check parameter from your data model.

  1. Open the data model that you secured via JWT ABAC beta token implementation and do the following:

    1. Delete the filter based on the security formula.

    2. Delete the security formula.

    3. Delete the security parameter.

    4. Click Save Changes.

  2. Authenticate your users with the token generated via /api/rest/2.0/auth/token/custom API endpoint. Authenticate users exclusively using POST /api/rest/2.0/auth/token/custom API endpoint. Ensure that variable_values are defined in the token.

This will result in the same filtering logic for that user, with the JWT ABAC Beta token no longer applied.

JWT beta migration test 3

Examples for mapping JWT ABAC Beta expressions to ABAC via RLS🔗

The following examples show how to map common JWT ABAC Beta expressions to equivalent RLS rules.

OperatorExpression in JWT ABAC BetaEquivalent RLS expression (ABAC via RLS)

EQ (equal)

"runtime_filters": [
  {
    "column_name": "Country",
    "values": ["Germany"],
    "operator": "EQ"
  }
]

country = ts_var(country_rls_var)

IN (in)

"runtime_filters": [
  {
    "column_name": "Country",
    "values": ["Germany","Australia"],
    "operator": "IN"
  }
]

country = ts_var(country_rls_var) (multi-value variable)

NE (not equal)

"runtime_filters": [
  {
    "column_name": "Country",
    "values": ["Germany"],
    "operator": "NE"
  }
]

country != ts_var(country_rls_var)

NOT_IN (not in)

"runtime_filters": [
  {
    "column_name": "Country",
    "values": ["Germany","Australia"],
    "operator": "NOT_IN"
  }
]

country != ts_var(country_rls_var) (multi-value variable)

Note

RLS supports multi-value variables and rich expression functions (such as contains). Choose the appropriate operator or function depending on how you want to evaluate lists or partial matches in your RLS rules.

Additional resources🔗

© 2026 ThoughtSpot Inc. All Rights Reserved.