aud is the scheme_id in JWT. The entity sending the API response shares this with the entity making the API requests. Setu would provide this value under credentials for making calls to Setu APIs. You should set this value and share it with Setu to enable Setu to make calls to your APIs.
iat is the epoch timestamp in seconds, at which the request was issued. Requests older than 30 seconds are considered stale, and hence will be rejected.
jti is a unique ID for every request that can be used to identify the request for logging, debugging and tracking purpose. Since this is unique for every request, the same JWT token should not be reused or repeated for different requests.
Using the algorithm specified in the header, along with the encoded header, encoded payload and secret, the signature is constructed in the following way—
base64UrlEncode(header) + "." +
The secret is a private key shared between Setu and you, used to sign the token to verify the sender of the JWT, ie, if the claims are coming from the aud that they claim to be coming from. The request is authenticated based on both the validity of the signature, and also the verification of each claim individually. For example—
The JSON Web Token mechanism is used for securely communicating with Setu. It is an open standard for representing claims securely between two parties.
The JWT website ↗ covers the basics of how it works and the concepts involved. This guide provides a simple description of how JWT is implemented at Setu.
For Setu products, JWT keys have a one-to-one mapping with individual product configurations. Essentially, each product configuration comes with its own JWT key that a merchant can use to authorise API requests.
While we support JWT auth, we recommend using the more secure OAuth keys, which come with features like the ability to access multiple products with the same key, or regenerate and delete keys as needed and so on.
A merchant will call Setu APIs for creating payment links, checking link status, for fetching reports etc and can use JWT to authenticate such requests with Setu.
If you are an Admin for your Bridge account, you should be able to see the API keys card under “Org settings” in the left panel. Click the JWT keys card to view keys for all your product configs. Read more ↗
Practically, you never need to worry about the encoding and decoding a JWT.
A lot of third party libraries exist that can do this for you easily —you can take a look at all the available libraries in most of the programming languages at Libraries for Token Signing/Verification section here ↗.
Setu / partner can accept a request as legitimate when the JWT format is recognised, ie, the payload is verified and the signature is valid. Requests can be rejected if—
The time since generation of the token is more than 2 minutes.