Nimbus JOSE + JWT

  • The most popular and robust Java library for JSON Web Tokens (JWT)
  • Supports all standard signature (JWS) and encryption (JWE) algorithms as well as secp256k1 used in Bitcoin and Ethereum
  • Open source Apache 2.0 license

Secure your tokens and APIs

This library implements the Javascript Object Signing and Encryption (JOSE) and JSON Web Token (JWT) specs, providing comprehensive yet easy to use security for:

  • Signing and encrypting tokens, such as self-contained OAuth 2.0 access tokens and OpenID Connect identity tokens
  • Security event tokens
  • Self-contained API keys, with optional revocation
  • Stateless sessions
  • Protecting arbitrary content and messages
  • Authenticating clients and web API requests

Hello, world!

// Create an HMAC-protected JWS object with some payload
JWSObject jwsObject = new JWSObject(new JWSHeader(JWSAlgorithm.HS256),
                                    new Payload("Hello, world!"));

// We need a 256-bit key for HS256 which must be pre-shared
byte[] sharedKey = new byte[32];
new SecureRandom().nextBytes(sharedKey);

// Apply the HMAC to the JWS object
jwsObject.sign(new MACSigner(sharedKey));

// Output in URL-safe format

Need more examples? We haven plenty of them!


For Java 7+ check out the latest release:


Go to the downloads page for more instructions.

Full compact JOSE and JWT support

Create, serialise and process compact-encoded

  • Plain (unsecured) JOSE objects;
  • JSON Web Signature (JWS) objects;
  • JSON Web Encryption (JWE) objects;
  • JSON Web Key (JWK) objects and JWK sets;
  • Plain, signed and encrypted JSON Web Tokens (JWTs).

The less frequently used alternative JSON encoding is on the road map.

All standard JWS and JWE algorithms are covered

Check our awesome cryptographic algorithm selection guide if you're unsure which one is the right for your app.


MAC / signature JWS alg identifiers
HMAC integrity HS256, HS384 and HS512
RSASSA-PKCS1-V1_5 signatures RS256, RS384 and RS512
RSASSA-PSS signatures PS256, PS384 and PS512
EC signatures ES256, ES256K, ES384 and ES512
EdDSA signatures EdDSA

Based on the standard secp256k1 curve. The JWS ES256K algorithm name and the SECP256K1 curve name are not officially registered yet.


Key management JWE alg identifiers
RSAES-PKCS1-V1_5 encryption RSA1_5
AES key wrap encryption A128KW, A192KW and A256KW
Direct shared symmetric key encryption dir
Elliptic Curve Diffie-Hellman key agreement ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW and ECDH-ES+A256KW
AES GCM key wrap encryption A128GCMKW, A192GCMKW and A256GCMKW
PBES2 key encryption PBES2-HS256+A128KW, PBES2-HS384+A192KW and PBES2-HS512+A256KW

Encryption methods JWE enc identifiers
AES/CBC/HMAC/SHA authenticated encryption A128CBC-HS256, A192CBC-HS384, A256CBC-HS512, A128CBC+HS256 (deprecated) and A256CBC+HS512 (deprecated)
AES in Galois/Counter Mode (GCM) A128GCM, A192GCM and A256GCM

Compression JWE zip identifier


Key type JWK kty identifier
RSA (RFC 3447) RSA
Elliptic Curve (DSS) EC
Octet sequence (symmetric key) oct
Octet key pair (RFC 8037) OKP

The JOSE / JWT layer is neatly decoupled from the underlying cryptography

Neat interfaces decouple the JOSE / JWT layer from the JWA cryptography code for signing / verification and encryption / decryption. Multiple JCA providers, including hardware-based (smart cards and HSM), are supported. You can use the available algorithm implementations or plug your own.


Use the comprehensive JavaDocs as API reference and to discover the library's many features and capabilities. You can browse the API docs online or download them from Maven Central.

Implemented specifications

From the JavaScript Object Signing and Encryption (JOSE) working group:

From the OAuth working group:

From the COSE working group:

  • Web Cryptography API -- W3C effort to specify a standard JavaScript API for performing cryptographic operations in the browser.

System requirements and dependencies

The Nimbus JOSE + JWT library works with Java 7+ and has minimal dependencies.

  • JSON Smart for highly efficient parsing and serialisation of JSON. The dependency is shaded since v9.0 to prevent potential version conflicts in projects with other dependencies on JSON Smart.

  • JCIP for concurrency annotations.

  • [optional] BouncyCastle can be used as an alternative crypto backend via the standard Java Cryptography Architecture (JCA) interface. Users typically resort to BouncyCastle if they run an older Java edition (6 or 7) that doesn't support certain JWS and JWE crypto operations. See JCA algorithm support for more info.

  • [optional] Tink for handling Ed25519 signatures and ECDH with X25519 (RFC 8037)

JWK generator

A tool for generating RSA, EC and symmetric JSON Web Keys (JWKs) is also available, thanks to Justin Richer. He also hosts an online version.


The library source code is made available under the Apache 2.0 license.

To post bug reports and suggestions

Your feedback is important. Read how to submit bug reports and suggestions. And here is a list of features that we want to implement.


Development of this library was started by Connect2id in January 2012. The initial code was based on JWS/JWE/JWT crypto classes factored out of the OpenInfoCard project. A rewrite to fully decouple the JOSE + JWT object representation from the crypto implementation led to the next major 2.0 release in October 2012. Today the library is used by our OpenID Connect server and numerous other products and services in identity, messaging, mobile and finance.


  • Axel Nennker and the developers behind OpenInfoCard for providing much of the initial code.
  • Justin Richer for handling initial releases to Maven Central, JPSK support, numerous improvements, fixes and suggestions.
  • Melisa Halsband from CertiVox for implementing AES key wrap and AES GCM key wrap encryption.
  • Tim McLean for implementing RFC 8037.
  • Cedric Staub for adding explicit JCA provider interfaces.
  • Toma Velev for implementing the JSON Smart shading in v9.0.
  • Ville Kurkinen for adding initial Maven support.
  • David Ortiz for initiating RSA encryption development.
  • Quan Nguyen, Google Information Security Engineer, Project Wycheproof, for reporting Padding Oracle and integer overflow vulnerabilities in AES/CBC/HMAC decryption.
  • Devin Cook of Oracle Cloud Infrastructure (OCI) - Security Research Team.
  • Juraj Somorovsky for security related reviews, improvements and suggestions.
  • Antonio Sanso for his work in investigating invalid curve vulnerabilities in JOSE implementations.
  • Lai Xin Chu for initial work on JWE.
  • Wisgary Torres from the Microsoft Xbox team for important feedback and bug reports.
  • Brian Campbell for JWT thumbprint debugging.
  • CertiVox UK for supporting the library development.
  • Casey Lee for adding a Java 6 build profile.
  • Dimitar A. Stoikov on adding support for AES ciphers with internally generated IV.
  • Aleksei Doroganov for adding ES256P support based on secp256k1 ECDSA.
  • Everyone on the JOSE WG at the IETF.
  • Numerous other contributors of bug reports, fixes and suggestions.