Skip to content

Fix Okta JWT Validation – Access Token Rejected

DodaTech Updated 2026-06-24 3 min read

In this tutorial, you'll learn about Fix Okta JWT Validation. We cover key concepts, practical examples, and best practices.

Your app receives an Okta JWT access token from the client, validates it, and gets: "JWT validation failed: invalid signature" or "The audience claim does not match". The token looks legitimate β€” it decodes fine on jwt.io β€” but your server won't accept it.

Wrong ❌

// Server-side token verification
const jwt = require('jsonwebtoken');

const decoded = jwt.verify(token, 'OUR_SECRET_KEY');
// Error: invalid signature

You hardcoded a secret key. But Okta issues JWTs signed with a private key, not a shared secret. You can't use a symmetric `HS256` secret β€” Okta uses `RS256` (asymmetric) by default.

Alternatively, you verify with the JWKS endpoint:

```<a href="/programming-languages/javascript/">javascript</a>
const jwksClient = require('jwks-rsa');
const client = jwksClient({ jwksUri: 'https://{yourOktaDomain}/oauth2/default/v1/keys' });
// Still fails: "kid not found"

## Right βœ…

**Correct JWT validation flow:**

```javascript
const OktaJwtVerifier = require('@okta/jwt-verifier');

const verifier = new OktaJwtVerifier({
  issuer: 'https://{yourOktaDomain}/oauth2/default',
  clientId: '{yourClientId}',
});

// Validate the access token
verifier.verifyAccessToken(token, '{expectedAudience}')
  .then(jwt => {
    console.log('βœ… Token is valid');
    console.log('Claims:', jwt.claims);
    // {
    //   sub: '00uid123...',
    //   aud: 'api://default',
    //   iss: 'https://{oktaDomain}/oauth2/default',
    //   iat: 1719123456,
    //   exp: 1719127056
    // }
  })
  .catch(err => {
    console.error('❌ Token validation failed:', err.message);
  });

**Manual validation with JWKS:**

```<a href="/programming-languages/javascript/">javascript</a>
const jwksClient = require('jwks-rsa');
const jwt = require('jsonwebtoken');

function getKey(header, callback) {
  client.getSigningKey(header.kid, (err, key) => {
    const signingKey = key.getPublicKey();
    callback(null, signingKey);
  });
}

const options = {
  algorithms: ['RS256'],         // ← must be RS256, not HS256
  issuer: 'https://{oktaDomain}/oauth2/default',
  audience: 'api://default',     // ← must match the token's aud
};

jwt.verify(token, getKey, options, (err, decoded) => {
  if (err) {
    console.error('❌', err.message);  // e.g. "jwt audience invalid"
  } else {
    console.log('βœ…', decoded);
  }
});

**Common JWT validation errors:**

| Error | Cause | Fix |
|-------|-------|-----|
| `invalid signature` | Wrong algorithm (HS256 instead of RS256) | Use RS256 with JWKS |
| `jwt audience invalid` | `aud` mismatch | Set `audience` to the token's `aud` claim |
| `jwt issuer invalid` | `iss` mismatch | Match the `issuer` field to `{oktaDomain}/oauth2/default` |
| `jwt expired` | Token past its `exp` | Refresh the token |
| `kid not found` | Key rotation race | Re‑fetch JWKS and retry |

## Root Cause

Okta signs access tokens with RS256 using a private key that rotates periodically. Your server must fetch the public key from Okta's JWKS endpoint and verify the signature with RS256. Using a hardcoded secret or the wrong algorithm causes validation failures.

## Prevention

- Always use the `@okta/jwt-verifier` library β€” it handles key rotation, <a href="/system-design/caching/">caching</a>, and algorithm selection.
- Cache the JWKS response and refresh it periodically (every hour or on failure).
- Log the `kid` header from rejected tokens to debug key mismatches.
- Use Okta's **claim sets** to control which claims appear in the token.


## Common Mistakes with jwt validation

1. **Using `head` and `tail` instead of pattern matching, causing runtime errors on empty lists**
2. **Forgetting that lazy evaluation defers computation until the value is forced, causing space leaks with unevaluated thunks**
3. **Using `return` to exit a function early instead of wrapping a pure value in the monad**

These mistakes appear frequently in real-world OKTA code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

## Practice Exercise

**Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.**

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

## FAQ

<details style="margin-bottom:12px;border:1px solid #e2e8f0;border-radius:10px;overflow:hidden"><summary style="cursor:pointer;padding:14px 18px;font-weight:600;font-size:1.05rem;background:#f8fafc;border-bottom:1px solid #e2e8f0;color:#1e293b">**Q: Should I validate access tokens or ID tokens?**</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>A: Access tokens protect your API. ID tokens identify the user. Validate access tokens with the audience; ID tokens with the client ID.</p>
</div></details><details style="margin-bottom:12px;border:1px solid #e2e8f0;border-radius:10px;overflow:hidden"><summary style="cursor:pointer;padding:14px 18px;font-weight:600;font-size:1.05rem;background:#f8fafc;border-bottom:1px solid #e2e8f0;color:#1e293b">**Q: How often does Okta rotate signing keys?**</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>A: Every 30 days by default. The old key is included in the JWKS response during the rotation window.</p>
</div></details><details style="margin-bottom:12px;border:1px solid #e2e8f0;border-radius:10px;overflow:hidden"><summary style="cursor:pointer;padding:14px 18px;font-weight:600;font-size:1.05rem;background:#f8fafc;border-bottom:1px solid #e2e8f0;color:#1e293b">**Q: Can I use HS256 (shared secret) instead?**</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>A: Yes β€” configure Okta to use HS256, but it's less secure. Recommended only for service‑to‑service communication.</p>
</div></details><details style="margin-bottom:12px;border:1px solid #e2e8f0;border-radius:10px;overflow:hidden"><summary style="cursor:pointer;padding:14px 18px;font-weight:600;font-size:1.05rem;background:#f8fafc;border-bottom:1px solid #e2e8f0;color:#1e293b">**Q: Where can I find the `audience` value?**</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>A: In the Okta API app β†’ <strong>General</strong> tab. The audience is usually <code>api://default</code> or the app's client ID.</p>
</div></details>

---

*JWT validation is covered in the [DodaTech Okta API Security course](https://dodatech.com/courses/okta).*

Built by the developers of DodaTech

Doda Browser, DodaZIP & Durga Antivirus Pro