superdiana/nexmo-jwt-jdk

Library to assist with generating JWT tokens for use with the Nexmo API.

Nexmo JWT JDK Library

This library provides a wrapper for generating JWTs using Nexmo-specific claims.

Learn more about Authenticating with JSON Web Tokens.

Installation

For Gradle:

repositories {
    mavenCentral()
}

dependencies {
    implementation 'com.nexmo:jwt:1.0.1'
}

For Maven:

<dependency>
  <groupId>com.nexmo</groupId>
  <artifactId>jwt</artifactId>
  <version>1.0.1</version>
</dependency>

Snapshot Repository

Snapshot releases happen periodically to test new functionality. If you'd like to use these versions, you can add the snapshot repository.

For Gradle:

repositories {
  maven {
    url 'https://oss.sonatype.org/content/repositories/snapshots/'
  }
}

For Maven:

<repository>
  <id>sonatype-snapshot</id>
  <url>http://oss.sonatype.org/content/repositories/snapshots</url>
  <snapshots>
    <enabled>true</enabled>
  </snapshots>
</repository>

Usage

The JWT library provides a Jwt.Builder which can be used to construct a Jwt representation. The Jwt class contains a generate() method for generating JSON Web Signatures that can then be used to authenticate with the API.

Generating a JWT

The API requires an application_id claim, and the token needs to be signed with a private key. The corresponding public key is uploaded to Nexmo for signature verification. The library expects you to provide a PKCS#8 key contents or file path.

Generating a JWT with Private Key Contents

To generate a JWT with these properties you can use:

Kotlin

val jws = Jwt.builder()
    .applicationId("your-application-id")
    .privateKeyContents("private key contents")
    .build()
    .generate()

Java

String jws = Jwt.builder()
        .applicationId("your-application-id")
        .privateKeyContents("private key contents")
        .build()
        .generate();

Generating a JWT with Private Key Path

You can also provide a Path to the location of your private key:

Kotlin

val jws = Jwt.builder()
    .applicationId("your-application-id")
    .privateKeyPath(Paths.get("/path/to/private.key"))
    .build()
    .generate()

Java

String jws = Jwt.builder()
        .applicationId("your-application-id")
        .privateKeyPath(Paths.get("/path/to/private.key"))
        .build()
        .generate();

Generating a JWT with Custom Claims

In some instances, you might want to define custom claims.

Kotlin

// Add them individually using addClaim
val jws = Jwt.builder()
    .applicationId("your-application-id")
    .privateKeyPath(Paths.get("/path/to/private.key"))
    .addClaim("foo", "bar")
    .addClaim("bat", "baz")
    .build()
    .generate()

// Or add multiples using a map
val jws = Jwt.builder()
    .applicationId("your-application-id")
    .privateKeyPath(Paths.get("/path/to/private.key"))
    .claims(mapOf("foo" to "bar", "bat" to "baz"))
    .build()
    .generate()

Java

// Add them individually using addClaim
String jws = Jwt.builder()
        .applicationId("your-application-id")
        .privateKeyPath(Paths.get("/path/to/private.key"))
        .addClaim("foo", "bar")
        .addClaim("bat", "baz")
        .build()
        .generate();

// Or add multiples using a map
String jws = Jwt.builder()
        .applicationId("your-application-id")
        .privateKeyPath(Paths.get("/path/to/private.key"))
        .claims(Map.of("foo", "bar", "bat", "baz"))
        .build()
        .generate();