Authentication tokens exist to answer one question: is this caller authorized to do this?
They are not intended to be a stable data interface, a schema you can depend on, or an input into application logic.
If your application decodes tokens and reads claims from them, this is an important heads-up.
Token Claims Were Never Guaranteed
Although tokens may appear readable today, that was never a promise. We have never publicly documented token contents, and as a result, we have always reserved the right to change token claims at any point, for any reason.
Claims may change, become optional, be renamed, be removed, or stop being readable altogether. Relying on decoded token contents may work today, but it has always been an unsupported and fragile pattern across the industry.
What’s Changing
Coming this summer, we will be further encrypting authentication tokens. In some scenarios, these changes may take effect even earlier, as we continue to evolve and change token formats. As this happens, token payloads will no longer be readable by clients. Any application that depends on decoding tokens to extract claims will break.
Applications that already treat tokens as opaque will not be impacted.
What to Do Instead
Tokens should be used only for validation and authorization. After validating a token, your application should rely on supported Azure DevOps REST APIs to retrieve user or organization data. Those APIs provide stable contracts, documentation, and clear expectations around change. Token claims do not.
As a rule of thumb:
- Use tokens to prove who the caller is and what they’re allowed to do
- Use supported APIs when you need actual data
- Assume any token claim may change or disappear without notice
If you find yourself decoding tokens to read values, that logic belongs elsewhere.
Final Reminder
If your application depends on decoded token claims, consider this your warning to move off that pattern now—especially before encryption is enforced this summer.
Authentication tokens are for authentication and authorization, not data access. Treat them as opaque, and use supported APIs instead.
The post Authentication Tokens Are Not a Data Contract appeared first on Azure DevOps Blog.