This has caused me a ton of confusion and my customers keep getting confused as well. Azure Active Directory has been around for some time now. Some time ago we added a new endpoint (V2) which is more standards compliant and supports both AAD and MSA accounts and for example features like incremental consent. Still people get confused about our numbering scheme and I totally understand why. Let me try to explain a little bit how this all works.

We have 2 versions of our token and authorization endpoints. These are the endpoints your applications talk to, to get authenticated and get tokens. You can see the different URL’s for these endpoints if you go to an application registration and click on endpoints.

As you can see in the URI the V2 endpoint points to https://login.microsoftonline.com/organizations/oauth2/v2.0/authorize. Of course organizations will be replaced with your tenantid if it’s a single tenant application only usable by your company or it can be /common if you support both AAD and MSA accounts.

Actually there isn’t a v1 endpoint, it is just the previous version and we now just call it v1 (but you don’t see v1 in the URI. )

ID Tokens

So how do I know if I get a V1 or V2 Identity or ID Token? That’s simple. If you ask for an ID token from the V1 endpoint, you get a V1 ID token. If you ask for an ID token from the V2 endpoint you get a V2 ID token. Obviously we show the version inside the token when we return it to you. That simple. The difference is mostly in the size of the tokens. For V2 we decided to optimize for size and a lot of claims aren’t part of the default token. They can be added by specifying which optional claims you want to add to the token. As a starting point you should always aim to smallest tokens as possible.

Information about ID token can be found here.
Sample V1 ID token.
Sample V2 ID token.

Access Tokens

Versions of access tokens have nothing to do with the version of the endpoints. Access Tokens versions are determined by the configuration of your application/API in the manifest. You have to change the accessTokenAcceptedVersion part of the manifest to 2 if you want a V2 access token. This is also the reason why you cannot control what version of the access token you will get from your client application when you request an access token. For example User.Read is an access token for MS Graph and those are always V1 access tokens.

Information about access tokens can be found here.
Sample V1 access token.
Sample V2 access token.

If you look at the tokens you will find the “ver” claim telling you which version the token is.

Also, the accessTokenAcceptedVersion is null by default and the system then defaults to V1 access tokens. I am not sure why the default is null in the manifest if you create an application registration. That we default to V1 tokens is probably because of compat reasons.

Optional Claims

If you need more information/claims in your tokens it’s possible to add optional claims. Fortunately there is a UI to do this nowadays. You can find more information about optional here.

Hope this clears up a bit the differences between V1 and V2 tokens.

Do I need to care about these versions?

Not really. It’s nice when tokens are smaller. The most important part is you talk to the V2 endpoint instead of the V1 endpoint. If you use MSAL that’s automatically happening already. That’s where all apps are moving too and that’s were all the new features will be ending up as well (think about things like passwordless and extra features around consent or code flow with PKCE for single page apps)