Session & single sign-on
The customer has already authenticated with you. They must not authenticate again. This page covers how that works, and what happens when they leave.
The flow
Three properties make this safe:
Your authentication is the trust anchor. Cheggout accepts your signed assertion that this
virtualId belongs to an authenticated customer. Nothing else vouches for the user.
The session is minted server-side. Minting requires your private key, so a client cannot create one.
sessionId is derived from virtualId. The two must be presented together at launch — a
mismatched pair will not authenticate.
Minting the session
Call GenerateSessionInfoV2 from your backend,
after your own authentication has succeeded.
{
"bName": "YOURCHANNEL",
"virtualId": "pub_8f14e45fceea167a"
}
{ "sessionId": "REPLACE_WITH_SESSION_ID" }
virtualId server-sideNever accept it from client input. If a client can name the user, a client can name another user and be issued a session for them. Resolve it from your authenticated session.
bNameMatched case-sensitively. GetAuthToken uses
channelName for the same concept. Follow each endpoint's own page.
Prerequisites
Agreed during onboarding:
- Public key certificates exchanged in both directions.
- Your server IPs whitelisted for session verification.
- A Virtual ID generation service available to Cheggout and to your application vendor, so the
same
virtualIdresolves consistently across parties.
Launching
Pass both values. The exact call depends on your surface:
| Surface | See |
|---|---|
| Android | Launching the SDK |
| iOS | Launching the SDK |
| Hosted | Launch URLs |
An invalid userID or session prevents the SDK from progressing past its initial screen — the
documented iOS symptom is a white page. If your integration hangs there, check that the virtualId
you launched with is exactly the one you minted the session for.
When to mint
Mint per launch. It is a single backend call, and it avoids depending on undocumented expiry behaviour.
TBD Session lifetime is not published. Do not cache a session across app launches or assume a duration. If you need to know how long a session survives — for a "resume where you left off" feature, say — confirm it with Cheggout.
Closing the session
When the customer presses back or home on the Cheggout home screen, the SDK session terminates and control returns to your app.
What happens next is your decision, and it is the one piece of session design you own:
Cheggout's SDK provides a heartbeat / Last Activity Time signal so your app knows the customer was active while inside the marketplace. Without it, a customer who spends ten minutes shopping looks idle to your app and may be logged out on return — a poor experience, especially in a banking app with a short idle timeout.
Wire the heartbeat if your app has an idle timeout. See Android callbacks and iOS callbacks, and Return handshake.
Security
- Mint only after your own authentication succeeds. The session is an assertion about an authenticated user.
- Keep the private key on your backend, in a secret manager.
- Verify Cheggout's response signature before using the
sessionId. - Treat
sessionIdas a credential — do not log it, and keep it out of URLs you control. - Use a pseudonymous
virtualIdwith no personal data in it.
Troubleshooting
| Symptom | Likely cause |
|---|---|
Signature Mismatch! | Signed the decoded JSON rather than the Base64 BDATA string |
| SDK opens to a blank screen | virtualId and sessionId do not correspond |
| Session rejected immediately after minting | Check the pair is passed unmodified from mint to launch |
| Customer logged out on return | Heartbeat not wired to your idle timer |
| Request never reaches the API | Egress IPs not whitelisted |