Issue a Custom JWT for Crossmint
On this integration path, you must perform four high level steps:- Create a public/private keypair
- Generate JWTs
- Expose a JWKS endpoint
- Pass the user’s JWT to Crossmint when using relevant APIs
Create the Public/Private keypair
To generate a private key for JWT (JSON Web Token) encryption, you can use several methods depending on your preferred programming language and toolset.Here’s how you can do it using openssl, a widely used tool for cryptographic operations:Store the base64 encoded version of the private key to your environment file and then remove the Next, you must extract the public key from the private key:Store the encoded public key to your environment file also:This approach helps ensure that your private key is stored securely. The corresponding public key can be used to verify the JWTs signed with the private key.
private_key_base64.txt
file from your system..env
.env
Creating the JSON Web Token
JSON Web Tokens, or JWT for short, are a standard way to encode a series of claims in a payload, that you sign, and can be verified later by a separate party (verifier, in this case, Crossmint) by using public key cryptography. Crossmint requires you to create a JWT with the following claims:Claim | Type | Required | Content |
---|---|---|---|
iss | string | yes | Your Crossmint project ID |
sub | string | yes | Unique identifier for this user. Use the same userId you use elsewhere when identifying this user in Crossmint APIs |
aud | string | array (string) | yes | ”crossmint.com” |
exp | int (unix timestamp in seconds) | no | The expiration time (unix seconds). Set it at a minimum to around 10m after it was issued. |
nbp | int (unix timestamp in seconds) | no | Not Before time (unix seconds). Tokens with this claim are valid from that moment forward. |
iat | int (unix timestamp in seconds) | no | The time in which the token was emitted. |
Config | Options supported | Recommended |
---|---|---|
Encoding | base64 | base64 |
JWS signing algorithm | RS256 | RS256 |
Encryption | none | none |
npm install jose
.
How to Test
Use the jwt.io token debugger to decode and inspect your tokens. You can also test locally on your machine decoding your own token and ensuring the fields are properly decoded, usingjose
.
Expose a JWKS Endpoint
In the step earlier, you learned how to create JWT tokens that Crossmint can interpret. However, in order for Crossmint to validate that these tokens are coming from your project and not an impersonator, Crossmint must validate their signatures against your public key. You must communicate to Crossmint what your public keys are by using a standard JSON Web Key Set endpoint (JWKS). This is a public API endpoint on your server where you can broadcast what are the current keys valid for your tokens. The reason why this is implemented as an API, instead of you passing Crossmint a static public key in the console, is in order to support key rotation of your JWT keys in the future. Below is a very basic examplePassing the JWT to Crossmint in API Calls
The last step to complete the loop is that when you’re invoking a Crossmint API, you must pass the JWT. At this time, the only API that uses it isgetOrCreateWallet()
in the Smart Wallet SDK, which takes the JWT as an input.