Auth Token Migration Guide

Oct 2, 2026

Themis-Trace now supports multi-tenancy. Every access token request must identify the tenant it belongs to. Your integration will continue working without changes for now, but each API consumer must include its tenant ID in token requests by December 31, 2026.

Before multi-tenancy

Themis-Trace used separate instances, so a URL, username, and password were enough to identify the caller. Authentication had two steps:

  1. Get a token. The application sends a POST request to the Auth Server's /connect/token endpoint with grant_type=password, its client_id, scope=ThemisTrace, and the user's username and password. The Auth Server returns an access_token.
  2. Call the API. Every API request includes the header Authorization: Bearer <access_token>. When the token expires, the application requests a new one.

What changed with multi-tenancy

The token request must now identify the tenant. Each tenant has its own users, and the same username can exist in more than one tenant. A username and password alone are no longer enough to identify the caller.

  • Token request: Send the tenant ID in the __tenant header. Without this header, the Auth Server looks for the user outside all tenants and the login fails.
  • Access token: The access_token now includes a tenantid claim for the tenant the user signed in to.
  • API calls: No change is required. The API reads the tenant from the token's tenantid claim, so API requests do not need the __tenant header.

What your application must change by December 31, 2026

Add the __tenant header, set to your Tenant ID, to every token request. Nothing else changes.

  1. Look up your Tenant ID. Call GET /api/abp/multi-tenancy/tenants/by-name/Your%20Tenant%20Name on the Auth Server. Replace Your Tenant Name with your actual tenant name and encode each space as %20. No sign-in is required. Use the tenantId value from the response. You can look it up by name at startup or store it in your application's configuration.
  2. Include it in the token request. Add __tenant: <tenant_id> to the POST /connect/token request alongside the fields you already send.
  3. Keep API calls unchanged. Continue sending Authorization: Bearer <access_token>. API calls do not need the __tenant header.
  4. Confirm completion. Email support@themis-trace.com once the change is complete.

Example tenant lookup and token request:

# 1. Look up your Tenant ID (read tenantId from the JSON response)
curl "https://<auth-server>/api/abp/multi-tenancy/tenants/by-name/Your%20Tenant%20Name"

# 2. Request a token for your tenant
curl -X POST "https://<auth-server>/connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "__tenant: <tenant_id>" \
  -d "grant_type=password" -d "client_id=<your_client_id>" -d "scope=ThemisTrace" \
  -d "username=<username>" -d "password=<password>"

Optional: confirm the token's tenant

This step is not required. It only confirms that the change worked. An access token has three parts separated by periods. The middle part contains its claims. Decode that part and confirm that tenantid matches your Tenant ID.

In PowerShell, with the token stored in $token:

$p = $token.Split('.')[1].Replace('-', '+').Replace('_', '/')
$p += '=' * ((4 - $p.Length % 4) % 4)
[Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($p))

The output is JSON that includes "tenantid": "<tenant_id>". Decode tokens on your own machine rather than using an online decoder. A token grants access until it expires.

Contact us

For questions or development support, email support@themis-trace.com.