Skip to main content

Verify tokens

Overview​

You can verify an OAuth2 Access Token in two ways:

  • By using a standard JWT, JSON Web Token, verification library
  • By calling the special introspection endpoint that gets exposed through the core service

One thing to note is that, besides the standard OAuth2 token claims, the Unified Login implementation includes an additional one called stt. This stands for SuperTokens Token Type. It ensures that the validation occurs for the correct token type:

  • 0 represents a SuperTokens Session Access Token
  • 1 represents an OAuth2 Access Token
  • 2 represents an OAuth2 ID Token.

The following guide covers only OAuth2 Tokens verification. For information on how to verify SuperTokens Session Tokens please refer to the following section.

Using a JWT verification library​

This is the standard validation method and you should use it for most of the operations that need protection. It indicates that the token is valid from a cryptographic standpoint and that it has not expired.

The code samples show you a basic validation scenario where the token undergoes a check for the required scope for an action to occur.

info

If your scenario involves a common backend with multiple frontend clients you can drop the client_id check.

App Info

Adjust these values based on the application that you are trying to configure. To learn more about what each field means check the references page.
This is the URL of your app's API server.
This is the URL of your app's API server.
SuperTokens will expose it's APIs scoped by this base API path.
This is the URL of your website.
The path where the login UI will be rendered

For NodeJS you can use jose to verify the token.

import jose from "jose";

const JWKS = jose.createRemoteJWKSet(new URL('<YOUR_API_DOMAIN>/authjwt/jwks.json'))

// Follow this example if you are using the Authorization Code Flow
async function validateToken(jwt: string) {
  const requiredScope = "<YOUR_REQUIRED_SCOPE>";
  const clientId = '<CLIENT_ID>';

  try {
    const { payload } = await jose.jwtVerify(jwt, JWKS, {
      requiredClaims: ['stt', 'scp', 'client_id'],
    });

    if(payload.stt !== 1) return false;
    if(payload.client_id !== clientId) return false;
    
    const scopes = payload.scp as string[];
    return scopes.includes(requiredScope);
  } catch (err) {
    return false;
  }
}

Email verification​

If you are using email and password based authentication, and you want to validate if the user has verified their email, you must check if the email_verified claim is true.

Using the token introspection API​

When a user logs out, their token gets removed from the SuperTokens Core database. That change does not reflect in token validation process that uses a JWT verification library. The token remains valid until its expiration time.

To ensure that the token remains valid, you can directly call the SuperTokens Core service. It is advisable to perform this process for high security operations to avoid the risk of a malicious agent using a token.

Here is an example of how you can use this validation method:

import OAuth2Provider from "supertokens-node/recipe/oauth2provider";

async function validateToken(token: string) {
  const { status } = await OAuth2Provider.validateOAuth2AccessToken(
    token,
    {
      clientId: "<CLIENT_ID>",
      scopes: ["<REQUIRED_SCOPE>"],
    },
    true
  );

  return status === "OK";
}