Vonage JWT

Common errors

• 401 Unauthorized

  cause The generated JWT is invalid, expired, or signed with an incorrect private key/application ID.
  fix Double-check your `application_id` and `private_key` for accuracy. Verify the private key file exists and its content is correct. Ensure the JWT hasn't expired prematurely due to clock skew.

• Invalid signature

  cause The JWT was signed with a private key that does not match the public key registered with your Vonage application, or the private key content is malformed.
  fix Confirm you are using the correct `private.key` file for the specified `application_id`. Ensure there are no extra spaces or line breaks when reading the private key content.

• JWT has expired

  cause The `exp` (expiration) claim in the JWT indicates it is no longer valid, or the `iat` (issued at time) claim is set in the future relative to the API server's time.
  fix Generate a new JWT. Ensure your server's time is synchronized. Review the JWT's claims (`iat`, `nbf`, `exp`) using a tool like jwt.io to confirm their validity.

• FileNotFoundError: [Errno 2] No such file or directory: 'private.key'

  cause The path provided for the private key file is incorrect or the file does not exist at the specified location.
  fix Verify the `VONAGE_PRIVATE_KEY_PATH` environment variable or direct path in your code points to the actual location of your `private.key` file. Ensure the script has read permissions for the file.

Warnings

• gotcha JWTs should always be generated on the backend. Exposing the private key or generation logic on the frontend is a significant security risk.
  Fix: Ensure all JWT generation occurs server-side, and only the generated token is sent to the client if needed.
• breaking Incorrect `application_id` or `private_key` will lead to authentication failures (e.g., '401 Unauthorized', 'Invalid signature', or 'Issuer not found').
  Fix: Verify that the `application_id` matches your Vonage application and the `private_key` is the correct, untampered key associated with it.
• gotcha JWTs are time-sensitive. If your server's clock is not synchronized or the 'iat' (issued at time) claim is in the future, tokens may be prematurely deemed expired, resulting in errors like 'JWT has expired' or '401 Unauthorized'.
  Fix: Ensure your server's system clock is synchronized with NTP. Validate JWTs for correct `iat`, `nbf` (not before), and `exp` (expiration) claims, typically handled by the library.
• gotcha When regenerating public/private key pairs in the Vonage Dashboard, always click 'Save changes' for the application. Failing to do so can lead to 'Invalid token' errors as the old keys remain active or the new ones aren't registered.
  Fix: After generating new keys, explicitly save the application settings in the Vonage Dashboard.
• gotcha For certain Vonage APIs (e.g., some Client SDK sessions), the 'sub' (subject) claim in the JWT must be the *username* and not the user ID. Using the wrong identifier can cause session timeouts.
  Fix: Refer to the specific API documentation to confirm the expected value for the 'sub' claim. If 'sub' is required, ensure it is populated with the username.

Install

• pip install vonage-jwt Install vonage-jwt

Imports

• JwtClient

  from vonage_jwt import JwtClient

Quickstart

This quickstart demonstrates how to initialize the `JwtClient` with your Vonage Application ID and private key, then generate an application-level JWT. It expects the application ID and private key path to be provided via environment variables for security. The private key content is read from the specified file path. Replace placeholders or set environment variables before running.

import os
from vonage_jwt import JwtClient

# It's recommended to load these from environment variables or a secure configuration.
VONAGE_APPLICATION_ID = os.environ.get('VONAGE_APPLICATION_ID', 'YOUR_APPLICATION_ID')
VONAGE_PRIVATE_KEY_PATH = os.environ.get('VONAGE_PRIVATE_KEY_PATH', './private.key') # Path to your private.key file

private_key_content = None
try:
    with open(VONAGE_PRIVATE_KEY_PATH, 'r') as f:
        private_key_content = f.read()
except FileNotFoundError:
    print(f"Error: Private key file not found at {VONAGE_PRIVATE_KEY_PATH}.")
    print("Please ensure the path is correct or the file exists.")
    # In a real application, you might want to raise an exception or handle this more robustly.

if VONAGE_APPLICATION_ID != 'YOUR_APPLICATION_ID' and private_key_content:
    try:
        jwt_client = JwtClient(VONAGE_APPLICATION_ID, private_key_content)
        jwt_token = jwt_client.generate_application_jwt()
        print(f"Successfully generated JWT: {jwt_token}")
    except Exception as e:
        print(f"Error generating JWT: {e}")
else:
    print("Please set VONAGE_APPLICATION_ID and ensure VONAGE_PRIVATE_KEY_PATH points to a valid private key file.")