Verify OAuth access tokens in your TanStack React Start application with Clerk

When building a resource server that needs to accept and verify OAuth access tokens issued by Clerk, it's crucial to verify these tokens on your backend to ensure the request is coming from an authenticated client.

Clerk provides a built-in getAuth() function that supports token validation via the acceptsToken parameter. This lets you specify which type(s) of token your API route should accept in your TanStack React Start application.

By default, acceptsToken is set to session_token, which means OAuth tokens will not be accepted unless explicitly configured. You can pass either a single token type or an array of token types to acceptsToken. To learn more about the supported token types, see the getAuth() parameters documentation.

Example 1: Accepting a single token type

In the following example, the acceptsToken parameter is set to only accept oauth_tokens.

• If the token is invalid or missing, getAuth() will return null for subject and other properties, and the request will be rejected with a 401 response.
• If the token is valid, it returns the authenticated user's subject and their associated scopes for use in the application logic.

export async function clerkAuth({ request }: { request: Request }) {
  const { subject, scopes } = await getAuth(request, {
    acceptsToken: 'oauth_token',
  })

  // If getAuth() returns null, the token is invalid
  if (!subject) {
    throw new Error('OAuth access token is invalid')
  }

  return { subject, scopes }
}

Example 2: Accepting any token type

In the following example, the acceptsToken parameter is set to accept any token type.

• If the token is a session_token, it logs that the request is from a user session.
• Otherwise, it logs that the request uses a machine token and specifies its type.

import { createServerFn } from '@tanstack/react-start'
import { getAuth } from '@clerk/tanstack-react-start/server'
import { getWebRequest } from '@tanstack/react-start/server'

const authStateFn = createServerFn({ method: 'GET' }).handler(async () => {
  const request = getWebRequest()
  const { tokenType } = await getAuth(request, { acceptsToken: 'any' })

  if (tokenType === 'session_token') {
    console.log('this is session token from a user')
  } else {
    console.log('this is some other type of machine token')
    console.log('more specifically, a ' + tokenType)
  }

  return {}
})