Protect a backend API
An external API receives a Clerk session token and must validate it before using the claims.
Clerk · Function
verifyToken
verifyToken() validates the signature of a Clerk-generated token and returns its verified claims. Use jwtKey for networkless verification or let Clerk retrieve JWKS from the Backend API.
How it works
Call verifyToken() with a Clerk-generated token and verification options. The function validates the signature either with the supplied JWT public key without network access or by retrieving JWKS from Clerk's Backend API, then resolves to the verified claims or a verification error.
Syntax
function verifyToken(token: string, options: { apiUrl?: string; apiVersion?: string; audience?: string | string[]; authorizedParties?: string[]; clockSkewInMs?: number; headerType?: string | string[]; jwksCacheTtlInMs?: number; jwtKey?: string; secretKey?: string; skipJwksCache?: boolean }): Promise<JwtReturnType<JwtPayload, TokenVerificationError>>Parameters
| Name | Type | Description |
|---|---|---|
token | string | The Clerk-generated token to verify. |
options | object | Verification settings, including apiUrl, apiVersion, audience, authorizedParties, clockSkewInMs, headerType, jwksCacheTtlInMs, jwtKey, secretKey, and skipJwksCache. |
Returns
Promise<JwtReturnType<JwtPayload, TokenVerificationError>>
Key points
- The function validates the cryptographic signature on a token issued by Clerk.
- Supplying jwtKey enables verification without contacting Clerk's Backend API.
- The first argument is a token string.
- A successful call resolves with the verified token payload.
Common mistakes
- Prefer authenticateRequest() for normal request authentication; verifyToken() is a lower-level API.
- Without jwtKey, verification can make a network request to obtain the JWKS.
- For networkless verification, jwtKey must contain the PEM public key from the Clerk Dashboard.
Example: Verify a Clerk token
import { verifyToken } from '@clerk/backend'
const claims = await verifyToken(token, {
secretKey: process.env.CLERK_SECRET_KEY,
})
console.log(claims.sub)Verifies a token with the backend secret key and reads the subject claim.
When to use it
Networkless verification
An edge or serverless service needs token validation without a network round trip.
Service-to-service authentication
A backend worker receives a bearer token from another service and needs to identify the user.
Interview questions
QWhat does verifyToken() do, and what does it return?
verifyToken() verifies the signature of a Clerk-generated token and returns a promise containing verified JWT claims or a token-verification error. It can use jwtKey for networkless validation or obtain JWKS from Clerk's Backend API.
Follow-up: How would you avoid a network round trip? Pass Clerk's PEM public key through the jwtKey option, commonly sourced from an environment variable.
QWhat are the main inputs to verifyToken()?
The token argument is the string being verified. The second argument contains options such as secretKey, jwtKey, audience, authorizedParties, clockSkewInMs, and headerType.
Follow-up: Which option checks that a token came from an expected frontend application? Use authorizedParties with the allowed application origins or parties.
QWhen should an application use verifyToken() instead of authenticateRequest()?
authenticateRequest() is recommended for fully authenticating a token from a request object. verifyToken() is a lower-level method for advanced cases where the token is already available or special verification control is needed.
Follow-up: When is verifyToken() particularly useful? It is useful for service-to-service or networkless token verification when the caller supplies the token and appropriate verification key or secret.
Related
authenticateRequest()getToken()JwtPayloadTokenVerificationError@clerk/backend