Action Required: Update Your JWT TTL Configuration for Enhanced Security Action Required: Update Your JWT TTL Configuration for Enhanced Security

Action Required: Update Your JWT TTL Configuration for Enhanced Security

Vonage API Support

Effective 30th November 2026, we are implementing stricter JWT Time-to-Live authentication requirements for all applications.

Applies To

Conversation, Device Location Retrieval, Dispatch, Identity Insights, Media, Messages, Quality on Demand, Verify, Voice, Video (Unified environment only)
How to recognize if I’m using Vonage Video API Unified Environment or Vonage Video API OpenTok environment?

What's Changing

New JWT Time-to-Live (TTL) Enforcement:

1. Maximum TTL Limit: 24 Hours

  • Hard Limit: Vonage will not accept any token that is more than 24 hours after the issued at time (iat), regardless of whether the expiration time indicates it to be valid still
  • This applies to: All JWT tokens used with Vonage APIs and Client SDKs
  • Security Rationale: Reduces the window of vulnerability if tokens are compromised

2. Required Claims Configuration

  • iat (Issued At Time): Must be present and accurate
  • exp (Expiration Time): Must be set to iat + maximum 24 hours
  • Fallback Behavior: If an expiration time (exp) has not been provided, then Vonage will accept the token for 15 minutes only

3. Validation Rules

  • Both iat and exp required: If both an issued at time (iat) and an expiration time (exp) have not been provided, then Vonage will reject the token
  • TTL calculation: exp must be ≤ iat + 86,400 seconds (24 hours)
  • Exception: Video tokens may be accepted for up to 30 days from iat.

Action Required

1. Update JWT Generation Logic

// Correct JWT payload structure
const currentTime = Math.floor(Date.now() / 1000); // Unix timestamp in seconds
const payload = {
  application_id: 'your-app-id',
  sub: 'username',
  iat: currentTime,                    // Issued at time (required)
  exp: currentTime + (24 * 60 * 60),   // Expires in 24 hours maximum
  acl: {
    paths: {
      "/*/users/**": {},
      "/*/conversations/**": {}
    }
  }
};

2. Review Current Token Lifetimes

  • Audit existing implementations that may set longer expiration times
  • Update any hard-coded expiration values exceeding 24 hours
  • Modify token refresh logic to accommodate shorter-lived tokens

3. Implement Proper Token Refresh

    Since tokens now have a maximum 24-hour lifetime, ensure your application:

  • Refreshes tokens before expiration (recommend refreshing at 23 hours)
  • Handles token expiration gracefully with automatic re-authentication
  • Stores and manages token lifecycle appropriately

Example Implementations:

Node.js with jsonwebtoken

const jwt = require('jsonwebtoken');
const generateToken = (applicationId, privateKey, username) => {
  const now = Math.floor(Date.now() / 1000);
  
  const payload = {
    application_id: applicationId,
    sub: username,
    iat: now,
    exp: now + (24 * 60 * 60), // 24 hours from now
    acl: {
      paths: {
        "/*/users/**": {},
        "/*/conversations/**": {}
      }
    }
  };
  
  return jwt.sign(payload, privateKey, { algorithm: 'RS256' });
};

PHP Implementation

use Vonage\JWT\TokenGenerator;
$generator = new TokenGenerator($applicationId, $privateKey);
$generator->setTTL(24 * 60 * 60); // 24 hours in seconds
$token = $generator->generateToken();

Python Implementation

import jwt
import time
def generate_token(application_id, private_key, username):
    now = int(time.time())
    
    payload = {
        'application_id': application_id,
        'sub': username,
        'iat': now,
        'exp': now + (24 * 60 * 60),  # 24 hours
        'acl': {
            'paths': {
                '/*/users/**': {},
                '/*/conversations/**': {}
            }
        }
    }
    
    return jwt.encode(payload, private_key, algorithm='RS256')

Benefits of This Change

  • Reduced exposure window if tokens are compromised
  • Improved compliance with security best practices
  • Better audit trail with shorter-lived credentials
  • Faster token validation with predictable expiration times
  • Reduced server load from long-lived token storage
  • More efficient token management

Testing and Validation

  1. Test in sandbox environment with updated TTL settings
    • [ ] iat claim is present and accurate
    • [ ] exp claim is set to iat + ≤ 24 hours
    • [ ] Token refresh occurs before expiration
    • [ ] Error handling for expired tokens works correctly
  2. Validate token generation using jwt.io or similar tools
  3. Verify token refresh logic works correctly
  4. Check application behavior near token expiration

Frequently Asked Questions

  1. Why the 24-hour limit? 
    This follows industry security best practices by limiting the exposure window if tokens are compromised while balancing usability.
  2. What happens to tokens with longer TTL already in circulation? 
    Existing tokens will automatically expire after 24 hours.  
  3. Can I request an exemption for a longer TTL? 
    The 24-hour limit is a platform-wide security policy with no exceptions. We recommend implementing proper token refresh mechanisms.

Additional Information

Articles in this section