Action Required: Update Your JWT ACL and Claim Configuration for Enhanced Security

Effective 30 November 2026, we are implementing stricter authorization of JWT tokens with Sub Claim for all client tokens.

1. New Requirement: 
   • All JWTs used with our client tokens must include the sub (subject) claim containing the correct username for in-app Voice.
   • JWT tokens with sub claim will need to contain in ACL list the API endpoints where request is sent. JWTs which are sent to the API endpoints not listed in ACL will be rejected.
2. Important: The sub claim must contain the username, not the user ID for in-app Voice.
3. Why This Matters: This improves protection against unauthorized access to the service

Applies To

• In-App Voice (Conversations)
• Verify Silent Auth
• Video (Unified environment only)
  How to recognize if I’m using Vonage Video API Unified Environment or Vonage Video API OpenTok environment?

Action Required

1. Update Your JWT Generation Code in-app Voice

• Ensure the sub claim is set to the correct username (not user ID)
• Verify this claim is included in all JWTs for authentication

2. Configure ACL Paths (regardless of API used):

• Review your application's API usage
• Set ACL permissions to include only the specific paths your application requires
• Common paths include:
  • /*/users/** (for user management)
  • /*/conversations/** (for conversation features)
  • /*/sessions/** (for session management)

Example JWT Payload Structure: 

{
  "application_id": "your-app-id",
  "sub": "correct_username",
  "iat": 1234567890,
  "exp": 1234571490,
  "acl": {
    "paths": {
      "/*/users/**": {},
      "/*/conversations/**": {},
      "/*/sessions/**": {}
    }
  }
}

Potential Impact

If you don't update your JWT configuration:

• Authentication failures for token users
• Degraded user experience in your application

Next Steps

• Review your current JWT configuration.
• Update Sub claim containing the correct username.
• Update ACL path to be more restrictive.
• Test the changes in your development environment first.

Additional Information

• Authentication documentation
• JWT Generator Tools
• Use jwt.io to validate your token structure
• Best-Security-Practices-for-Your-Vonage-API-Account