Using JWT

What is JWT?

JWT is the abbreviation of JSON Web Tokens. JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object.

The information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret

JWTs are stateless, decentralized, they support claims inside the token and they auto expire

What is the structure of a JWT

A JWT contains three components.

Header

This contains the encoding algorithm of a JWT.
We use HS256

Payload

This is used to identify user as Guest or Connected
Only below payload is acceptable while creating JWTs -

Guest User

{ 
  guest: true
}

Connected user

{ 
  smallcaseAuthId: <smallcaseAuthId string>
}

You may also add expiry to the JWT payload

Signature

Each partner is assigned & shared a unique JWT encoding secret
You can use the shared secret to encode the JWT with the payload as applicable
JWTs created with faulty secrets are rejected with error

Note: to ensure the secrecy of secrets, it is recommended to create JWTs on the server & not on client

What do we use JWTs for?

We use JWTs for two purposes -

1. To verify if the request is coming from an authorized Gateway partner. We do this by verifying the signature of the JWT (JWT must be created using the secret provided to you)
2. Consume the payload to identify the user as guest or connected user

Where to use JWT in the integration?

JWTs are required to consume both Gateway APIs & client-side SDKs

Client-side SDKs

Here the JWT is consumed in the intialization of the sdk.

• In Web Integration it is consumed as smallcaseAuthToken key in the scGateway class initialization
• In Android Integration, it is required as a param to init method
• In iOS Integration, it is required in the initializeGateway method as sdkToken
• In Cordova Integration, it is passed as a parameter to initSCGateway method as authToken as the key
• In React Native Integration, it is a parameter to the init method on react-native interface

Backend APIs

Here the JWT is passed as a authentication header with key x-gateway-authtoken