JWT Signature

The JWT Signature feature signs every API payload with a JSON Web Token (JWT). This cryptographic signature guarantees the authenticity and integrity of the data, ensuring that the payload has not been altered in transit.

Manage your JWT keys in the API Keys section of the dashboard.

---

How It Works

After activating the feature, each response includes a jwt field:

{
  "clusterUUID": "...",
  "botScore": ...,
  "browserTraits": { ... },
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

---

Verifying the JWT

Node.js (jsonwebtoken)

import jwt from 'jsonwebtoken';

function decodeToken(token, secretKey) {
  try {
    const payload = jwt.verify(token, secretKey);
    return payload;
  } catch (err) {
    return null; // invalid token
  }
}

Python (pyjwt)

import jwt

def decode_token(token: str, secret_key: str):
    try:
        payload = jwt.decode(token, secret_key, algorithms=["HS256"])
        return payload
    except jwt.PyJWTError:
        return None

Go (github.com/golang-jwt/jwt/v5)

import (
    "github.com/golang-jwt/jwt/v5"
)

func DecodeToken(tokenStr string, secretKey []byte) (map[string]interface{}, error) {
    token, err := jwt.Parse(tokenStr, func(t *jwt.Token) (interface{}, error) {
        return secretKey, nil
    })
    if err != nil || !token.Valid {
        return nil, err
    }
    return token.Claims.(jwt.MapClaims), nil
}

Java (io.jsonwebtoken)

import io.jsonwebtoken.*;

public Map<String, Object> decodeToken(String token, String secretKey) {
    try {
        Claims claims = Jwts.parser()
            .setSigningKey(secretKey.getBytes())
            .parseClaimsJws(token)
            .getBody();
        return claims;
    } catch (JwtException e) {
        return null;
    }
}

---

Post-Verification Checklist

1. Signature Valid? Ensure your verification function returns a non-null payload.

2. Issued-At (iat) Fresh? Reject tokens older than ~30 seconds (adjust to your threat model).

   {
     "iat": 1704067200  // Mon, 01 Jan 2024 00:00:00 UTC
   }

3. Proceed With Confidence Only trust and use the decoded data after these checks pass.

Security Best Practice
Rotate your JWT signing keys regularly and store them securely to minimize risk.

---