Troubleshooting Zoom Meeting SDK signature validation

In this guide, we’ll cover common issues you may run into when generating a signature for the Zoom Meeting SDK.

The Zoom Meeting SDK uses a JSON Web Token (JWT) signature to authorize the SDK and validate your client’s requests to start or join a meeting.

Documentation on this is available here: Meeting SDK Authorization .

We also have a sample signature application which can be used as a good starting point: Sample Meeting SDK Signature App - Node JS

If the signature provided is invalid, the SDK will most commonly respond with one of the following error messages:

Signature is invalid
Invalid SDK App Keys

Invalid signature tokens

Signature tokens may be invalid if they are missing expected formats or fields. If you have an invalid signature, verify the following:

The token has all required fields.
Values in the token are correct
The token exp date matches the expected rules.

Timestamps and expired tokens

Zoom uses Unix Epoch time to determine the creation and expiration time of the token.

The Meeting SDK expects a minimum JWT exp date of 1800 seconds (30 mins) greater than iat value and a maximum value of 48 hours greater than the iat value.

When checking timestamps and expiration, ensure the following:

iat value is the current time.
iat value is long format, not a string.
tokenExp or exp should be in Unix Epoch time.
exp value is greater than tokenExp.

Ensure your server clock has not drifted, and verify the token’s validity period. Epochconverter provides an easy-to-use interface for getting the current date and time in epoch format and future dates.

Example Meeting SDK JWT payloads

The header for the Meeting SDK JWT will be the same across all platforms; however, the payload properties for Mobile/Desktop and Web are slightly different. See examples below:

Web SDK signature payload

For the Web Meeting SDK, include the sdkKey, mn, role, iat, exp, and tokenExp properties. The values for exp and tokenExp will be the same.

{
  "sdkKey": SDK_KEY,
  "mn": MEETING_NUMBER,
  "role": ROLE,
  "iat": 1646937553,
  "exp": 1646944753,
  "tokenExp": 1646944753
}

Mobile/Desktop SDK signature payloads

For apps built using a mobile or desktop Meeting SDK (iOS, Android, macOS, Windows, Electron), include the appKey, exp, and tokenExp properties. The values for exp and tokenExp will be the same.

{
  "appKey": SDK_KEY,
  "iat": 1646937553,
  "exp": 1646944753,
  "tokenExp": 1646944753
}

Web and Mobile/Desktop signatures

For a signature generation function that works across web, mobile, and desktop platforms, include the appKey, sdkKey, exp, tokenExp, mn, and role properties. The values for appKey and sdkKey will be the same, and the values for exp and tokenExp will be the same.

{
  "appKey": SDK_KEY,
  "sdkKey": SDK_KEY,
  "mn": MEETING_NUMBER,
  "role": ROLE,
  "iat": 1646937553,
  "exp": 1646944753,
  "tokenExp": 1646944753
}

Steps to troubleshoot

Reproduce with the sample Node.js app
If you are generating a signature in your application and still getting an invalid signature error, the best first step is to test your credentials with the sample app. For a low-effort way to test manually, take the generated signature from the sample app and enter the signature property value for the SDK. This helps to compare your signature and isolate whether your function is generating the signature correctly.
Verify with JWT.io

JWT.io provides an excellent tool to decode and debug a JSON Web Token. You can use this tool to verify your token’s structure or build a token using a header and payload.

The header includes the signing algorithm and the token type. The payload section describes the authorization granted. It contains the token’s claims, the information passed about the user, and any metadata required.

If signature validation is failing, use JWT.io to decode the signature and verify its format and property values. Here is a demo of what that looks like :

While JWT.io is a great tool for decoding the signature and verifying its format and property values, it's also useful to know how to manually generate an SDK JWT with JWT.io. The video below provides a step-by-step walkthrough of how to do this when starting with the macOS Meeting SDK. In the walkthrough, the SDK JWT used to authorize the SDK is manually generated to rule out any issues with SDK JWT authentication.

Common SDK JWT Validation Issues:

If none of the above works, here are common issues we’ve seen:

Make sure you’re using a Meeting SDK app type, not OAuth or server-to-server OAuth.
If you’re using Math.round() in JavaScript, verify that you’re not returning a timestamp 10-30 seconds greater than your intended value.
Verify the local time on your computer is auto-syncing the system time correctly. It is recommended to generate the signature on the server side, in UTC / GMT to avoid timezone/time sync issues, and also to keep your Client Secret, Secret!
Verify the JSON header or payload uses curly quotes instead of straight quotes.
Verify tokenExp is larger than exp
Verify timestamps are in Unix epoch format and satisfy the following:

Conclusion

In this article, we discussed the process of troubleshooting and resolving Zoom Meeting SDK JWT signature validation issues. We covered how to manually encode and decode SDK JWT, along with methods to validate the signature JSON headers or payload. You can apply this process to other similar situations where you have leveraged JWT with your application. Keep in mind that these methods are not exhaustive, so feel free to share any tips in the comments if anything was missed.