MIRACL Trust uses JWTs (JSON Web Tokens) to deliver secure, stateless, and standards-compliant authentication that integrates easily with modern systems.
After a successful authentication, a JWT authentication token is generated and then sent to the application server for verification.
When the application server receives the token, it must verify that it was issued by MIRACL Trust and hasn’t expired. For this verification, you must use a JWT library suitable for your backend. To verify the token signature, use the MIRACL Trust JSON Web Key Set (JWKS) endpoint.
After the client fetches the JWKS, it caches the keys for subsequent requests
and uses them to validate JWTs. It might need to fetch them again periodically
to ensure they are up to date or to request them again if a token arrives with
an unknown key ID. Make sure your implementation does not assume the keys don’t
change, as they are periodically rotated to maintain security. Each JWT includes
a key ID (kid) in its header, identifying the specific key used for signing.
When a new signing key is introduced, JWTs issued thereafter will contain the
new kid. To ensure proper validation, your implementation should detect
unrecognised kid values and respond by fetching the updated JSON Web Key Set
(JWKS) from the MIRACL Trust endpoint at
https://api.mpin.io/.well-known/jwks.
The algorithm and the ID (kid) of the key used for signing the token are in
the following form:
{
"alg": "RS256",
"kid": "qT0Ifai8K3sd"
}
If a JWT fails validation due to an outdated keyset (i.e. the kid in the JWT header is unknown and the JWT is issued after the keyset was last updated), the client refetches the JWKS, caches it and retries validation.
# JWT Payload Validation
For security reasons, after verifying the signature, it is very important to validate the payload claims of the token. The payload is in this form:
{
"aud": "53ebbd21-05a2-410c-8817-03f0c2bf0350",
"exp": 1744269055,
"iat": 1744268995,
"iss": "https://api.mpin.io",
"sub": "bob@miracl.com"
}
- aud (audience) - must contain the Project ID.
- exp (expiration) - the token must not have expired. The expiration claim is a Unix timestamp.
- iat (issued at) - the time at which the token was issued. This claim is a Unix timestamp.
- iss (issuer) - must be
https://api.mpin.io. - sub (subject) - the User ID.
After the token is verified, the application server can create an application session for the user with the appropriate authorisation.
