User & broker sessions
Try Demo

User & broker sessions

When a partner’s user interacts with smallcase Gateway and completes a transaction with his broker account for the first time, a unique id called smallcaseAuthId is created to uniquely identify that user and his broker account.

smallcaseAuthId is shared with the partner in the response to all gateway transactions.

Note: In case of client-side, smallcaseAuthId can be achieved by decoding the smallcaseAuthToken received in the response
In case of webhook response, smallcaseAuthId is shared as part of the data

Gateway partners must save the smallcaseAuthId as part of their user’s records.

For the returning journeys of this user, it is important to trigger Gateway interactions with the same smallcaseAuthId as the payload of smallcaseAuthToken(JWT created with shared secret). smallcaseAuthId when passed while initializing Gateway or creating a transactionId, allows Gateway to prompt the user to login with his last used broker account. If the user tries to login with a different broker account, Gateway rejects the transaction with user_mismatch error.

Gateway partners must also make sure to not save the same smallcaseAuthId for two users. If this happens, it would mean that both users are using same broker account

Example 1 -
User A initializes Gateway for the first time on a partner app, hence smallcaseAuthToken is created for guest mode. User A would login with his broker account brokerA and Gateway partner will receive smallcaseAuthId authIdA for user A.
For all subsequent sessions of user A, Gateway should be initialized & transactionIds should be created with smallcaseAuthId authIdA. Since Gateway maintains a map of authId authIdA to broker account brokerA, any subsequent transaction will be successful for user A only if he uses broker account brokerA

Example 2 -
User B initializes Gateway for the first time on a partner app in guest mode while broker account brokerA is loggedIn in the browser, if the user B continues with the same broker account, Gateway will return smallcaseAuthId as authIdA corresponding to broker account brokerA.
In this case, Gateway partner is expected to put a check if authIdA is already saved as smallcaseAuthId for another user (User A in this case)

Key Takeaways -

  1. smallcaseAuthId is generated when a user uses Gateway to login with his broker for the first time. This id must be saved with the user records by the gateway partner

  2. smallcaseAuthId will always be unique to a user. No two users can have same smallcaseAuthId, unless both are using same broker account

  3. Whenever using any Gateway API/method for a connected user (where smallcaseAuthId is available), smallcaseAuthToken must always be created with smallcaseAuthId as payload. This should be done for all Gateway frontend & backend APIs/methods

  4. Gateway partner must always validate the response from all Gateway methods/APIs for the smallcaseAuthId for which the transaction/method was triggered to maintain sanity