Managing JWTs

JSON Web Tokens (JWTs) are a compact, URL-safe means of representing claims to be transferred between two parties. Vonage uses JWTs for authentication to a variety of APIs on both the front-end and the back-end; for a full list of the APIs that use JWTs, see the table in the Authentication guide.

Generating JWTs

The Vonage CLI contains a vonage jwt create command that can be used to generate JWTs. To use the command, you must have both your app-id and private-key. The private key is generated from the application dashboard, or by running vonage apps create. You can find more information on this command in Managing Applications.

When creating the JWT, you can either pass in a file path pointing to your private key file, or save this information for the CLI by running vonage auth set (see here for more information). The contents of the private key will then be saved in either the .vonagerc file or $HOME/.vonage/config.json.

Vonage Credentials:

Flag Description Type
--app-id The ID of the application to use. This is found in the "Applications" section of the dashboard or outputted with vonage apps. String
--private-key The path or contents of the private key. The private key can only be accessed when the application is created or when you regenerate the keys in the dashboard. String

**JWT Options:**
Flag Description Type
--exp The timestamp the token expires Number
--ttl The time to live in seconds Number
--sub The subject of the token String
--acl The access control list for the token String
# A command with parameters
vonage jwt create `
--app-id='00000000-0000-0000-0000-000000000000' `
--private-key=./private.key

# Will produce a token
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MzYyODE5NDYsImp0aSI6IjBmZjcwZDNmLTAzN2EtNGY4MC04ODZjLWI3MmM3MmQyMWNmMiIsImlhdCI6MTczNjI4MTA0NiwiYXBwbGljYXRpb25faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAifQ.gA7jClpqaZ2OoS0iri-zGCbda4jO7C0M8mka0EnSyjlds1EeY8fNoBEx3FTXHfkkzzrj0TskrWc_dcs1wuM8Kx55c5rLQ7taVpDAYopKSc_CeeOaad8S6aWnRkTUTNeduO4aIn-0CbyRTluBYsH1RBqYBQvobuQIDEwbFw8xBgx0UfREMMN6DAWknR57eiVXN9x_oD6CGQJ1yV3025nGboeMsP9YgX4Nwc-rE2r8c1ZGwCLO81x8i19Qil3Nwu5q1nzouyavQjIw00B_TZkushnI1ufdi_GNqk-h5q2HvGkg7Pj9bVkZHFdVTO8im03JYNyJmcV83vnpjOLuCFRzxQ

Access Control List (ACL)

If you're generating a JWT for use with the Vonage Client SDKs, you may need to specify an ACL, which is used to specify permissions for users.

In the CLI, an ACL is set using the --acl flag. In the example below, you can see the path object, which contains a list of different endpoints that correspond to different permissions granted to the user. A full list of these endpoints can be found in the Authentication guide.

# A command with parameters
vonage jwt create `
--app-id='00000000-0000-0000-0000-000000000000' `
--private-key=./private.key `
--sub='Alice' `
--acl='{\"paths\":{\"\/*\/users\/**\":{},\"\/*\/conversations\/**\":{},\"\/*\/sessions\/**\":{},\"\/*\/devices\/**\":{},\"\/*\/push\/**\":{},\"\/*\/knocking\/**\":{},\"\/*\/legs\/**\":{}}}'

# Will produce a token
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2wiOnsicGF0aHMiOnsiLyovcnRjLyoqIjp7fSwiLyovdXNlcnMvKioiOnt9LCIvKi9jb252ZXJzYXRpb25zLyoqIjp7fSwiLyovc2Vzc2lvbnMvKioiOnt9LCIvKi9kZXZpY2VzLyoqIjp7fSwiLyovcHVzaC8qKiI6e30sIi8qL2tub2NraW5nLyoqIjp7fSwiLyovbGVncy8qKiI6e319fSwiZXhwIjoxNzQxMTgyMzA3LCJzdWIiOiJBbGljZSIsImp0aSI6Ijg1MTViNzk2LTA1YjktNGFkMS04MTRkLTE1NWZjZTQzZWM1YiIsImlhdCI6MTc0MTE4MTQwNywiYXBwbGljYXRpb25faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAifQ.BscMdDXZ1-nuLtKyPJvw9tE8E8ZjJvTPJPMT9y0TjPz4Q7qqNaqxcjglc5QPtYEjh2YpZH6btSKbUF4XTClI026Hl5_QOBlnayYo7jXwhba16fa5PeyzSf30QFGFrHbANwrQJFVCjd329SZUpwK4GxgB1gf230NhbfmkhegKezqicru2WTGCKm8kQncYliFwIEYUlcRAb2c8xcaVrn_6QNNahyeJRwGFfWpIkX0Oe-S4RDlPjoq47_gYWac9MmaetB4Dd3Yp531AuniGV5JiIShkaEwuY4Zyov4Hcmajm4Lm_UFY119la7vzHis0P7cT9pPUDe5cyPj7eT8-VhitfQ

Validating JWTs

The vonage jwt validate <token> command can be used to check that the token is correctly signed to your application, but it can also check the other claims as well. This can be helpful if you encounter authentication issues when making API calls.

By default, the private key and application id from the config will be used; you can check those values using vonage auth show.

If you want to validate a token with a different private key or application id, you can use the --private-key and --app-id flags to overwrite them.

Vonage Credentials:

Flag Description Type
--app-id The ID of the application to use. This is found in the "Applications" section of the dashboard or outputted with vonage apps. String
--private-key The path or contents of the private key. The private key can only be accessed when the application is created or when you regenerate the keys in the dashboard. String

**JWT Options:**
Flag Description Type
--sub The subject of the token String
--acl The access control list for the token String
vonage jwt create <JWT Token> `
--app-id='00000000-0000-0000-0000-000000000000' `
--private-key=./private.key `
--sub='Alice' `
--acl='{"paths":{"/*/rtc/**":{},"/*/users/**":{},"/*/conversations/**":{},"/*/sessions/**":{},"/*/devices/**":{},"/*/image/**":{},"/*/media/**":{},"/*/applications/**":{},"/*/push/**":{},"/*/knocking/**":{},"/*/legs/**":{}}}' `
--exp=872827200

✅ Token was signed with the correct private key
✅ Token has not expired
✅ Application Id [00000000-0000-0000-0000-000000000000] matches [00000000-0000-0000-0000-000000000000]
✅ Subject [Alice] matches [Alice]
✅ ACL matches
  ✅ [ANY]  /*/rtc/**
  ✅ [ANY]  /*/users/**
  ✅ [ANY]  /*/conversations/**
  ✅ [ANY]  /*/sessions/**
  ✅ [ANY]  /*/devices/**
  ✅ [ANY]  /*/image/**
  ✅ [ANY]  /*/media/**
  ✅ [ANY]  /*/applications/**
  ✅ [ANY]  /*/push/**
  ✅ [ANY]  /*/knocking/**
  ✅ [ANY]  /*/legs/**
✅ All checks complete! Token is valid