Appearance
Authentication
Service path: /json/authentication
All authentication methods use the standard RPC envelope. Most of them also take a fixed systemCredentials block that identifies the GET Mobile client itself.
json
{
"systemCredentials": {
"domain": "",
"userName": "get_mobile",
"password": "NOTUSED"
}
}IMPORTANT
userName is literally get_mobile and password is literally NOTUSED. This is the client identity the server expects; it is not a secret you need to obtain.
Two Session Types (and a Token)
The API has two unrelated session ids, plus a derived session token. Mixing them up is the most common cause of 4001 / 4002 session errors.
| Wire exception | Meaning |
|---|---|
4001|Session not found | The session id is unknown or expired |
4002|No user associated with this session | The session is valid but has no patron/guest attached (a system session) |
| Artifact | Created by | Scope | Lifetime | Persisted in the app? |
|---|---|---|---|---|
| System session | authenticateSystem | Institution/service. No user. | One app run | No — in-memory field systemSessionId |
| User session | authenticateUser / authenticateGuestUser / authenticatePIN | One logged-in patron or guest | Until the server expires it | Yes — storage key get_sessionId |
| Session token | getAuthenticationToken | A hosted-web handoff derived from the current session | Short-lived | Only inside URLs it is handed to |
The system session ("computer" session)
authenticateSystem returns a session that is not tied to a person. It is what the app uses before anyone logs in: institution lookup, settings, content strings, and merchant menus. It is created once per app run and cached only in memory.
plaintext
POST /json/authentication method: authenticateSystem
→ "{SYSTEM_SESSION_ID}"- Cleared on logout (
clearSystemSession()sets it back tonull); the next need mints a new one. - Never written to storage, so a cold start always mints a fresh one.
- Sending it where a user session is expected produces
4002|No user associated with this session.
The user session
Every patron/guest login returns a session id string. The app overwrites the stored get_sessionId value with it at high priority, which is what enables auto-login and biometric unlock.
- A guest login (
authenticateGuestUser) is still a user session, just with theguestUserflag set on the user record. authenticatePINmints a new user session fromdeviceId+ PIN, so the password is not needed again.- Logout deletes/clears the stored value.
How the app decides which session to attach
For any request flagged useSessionId, the interceptor resolves a session in this order:
| Priority | Source | When |
|---|---|---|
| 1 | params.sessionId already present | The caller passed an explicit id (used by a few pre-login calls). |
| 2 | Cached user session (get_sessionId) | Whenever somebody is logged in. |
| 3 | System session | No user session exists; authenticateSystem is called lazily once. |
The same precedence applies to institutionId (explicit param → cached institution).
WARNING
The interceptor prefers the user session, not the system session. If you mirror this, don't overwrite an active user session with a freshly minted system session — calls that need a patron will fail with 4002.
How the App Chooses a Login Flow
There are two ways to obtain a user session, and the institution record decides which one the app uses. Two fields are involved, and they are separate enums — do not confuse them.
| Field | Type | Values | Effect in the app |
|---|---|---|---|
institution.authenticationSystemType | number | 1 HOSTED, 2 LDAP, 3 SSO_GENERIC, 4 CAS, 5 OKTA, 6 OKTA_EXT | Labels/affordances on the in-app login form |
institution.authenticationInfo.authenticationType | string | "CAS", "SSO_GENERIC", "OKTA_EXT" | Switches the app to the external browser login |
If authenticationType is one of those three strings, the app never shows a password field: it sends the user to the institution's hosted login page. For everything else (including a missing or unrecognised authenticationInfo) it shows the in-app form and calls authenticateUser.
External (hosted) login
The app builds the institution's login URL from the environment's
site_urland the institution'sshortName:plaintext{site_url}/{shortName}/full/login.php?mobileapp=1For production Northeastern that is
https://get.cbord.com/northeastern/full/login.php?mobileapp=1. This is the same page the wrapper's/api/v2/loginuses as itsRelayState.It opens that URL in an in-app browser (
_blank, WKWebView on iOS, cache and cookies cleared) and watches everyloadstartevent.When the URL contains
mobileapp_login_validator.php, the app takes the query string and uses its value as the user session id:jssessionId = url.split("?")[1].split("=")[1];It writes that id to the same storage key as a normal login (
get_sessionId, high priority) and runs the post-login state machine: if the institution enables mobile PIN and the user preference says so, it prompts for a PIN (and offers biometrics); otherwise it goes straight to the dashboard.
WARNING
The client does not validate the host of the URL that delivers the session — any page loaded in that browser whose URL merely contains mobileapp_login_validator.php is accepted. The parse is also positional: a second = or an extra query parameter (?sessionId=x&state=y) yields the wrong value. Both are client-side behaviours; see Security Notes #7.
Log In with Username and Password
Authenticates a patron or guest and returns a session id.
plaintext
POST /json/authentication
method: authenticateUserParameters
| Field | Type | Required | Description |
|---|---|---|---|
systemCredentials | object | YES | Fixed get_mobile block above. |
userCredentials.userName | string | YES | Patron username (often the campus card number or directory id). |
userCredentials.password | string | YES | Patron password. |
userCredentials.domain | string | YES | Usually "". |
userCredentials.institutionId | string | YES | UUID of the institution being logged into. |
Request
json
{
"method": "authenticateUser",
"params": {
"systemCredentials": {
"domain": "",
"userName": "get_mobile",
"password": "NOTUSED"
},
"userCredentials": {
"userName": "{USERNAME}",
"password": "{PASSWORD}",
"domain": "",
"institutionId": "{INSTITUTION_UUID}"
}
}
}Success Response
response is the session id string (not an object):
json
{
"response": "{SESSION_ID}",
"exception": null
}Send this value as params.sessionId on subsequent calls.
Failure Response
json
{
"response": null,
"exception": "AuthenticationFailureException|Login failed"
}Common codes: AuthenticationFailureException, BadPasswordException, MaxBadPasswordFailureException, InstitutionInactiveException, NoSuchUserException, UserNotConfirmedException.
Log In as a Guest
Same as
authenticateUser, but uses theauthenticateGuestUsermethod name.
plaintext
POST /json/authentication
method: authenticateGuestUserParameters are identical to authenticateUser. The app chooses this method automatically when the session was flagged isGuestUser.
NOTE
Guest login must be enabled for the institution (get.feature.guest_login). If it is not, the app falls back to the full website and shows Guest logins are not currently supported on GET mobile, you have been redirected to the full site.
Authenticate a System Session
Obtains a session id that is not tied to a user. Used before login and for institution-scoped calls.
plaintext
POST /json/authentication
method: authenticateSystemRequest
json
{
"method": "authenticateSystem",
"params": {
"systemCredentials": {
"domain": "",
"userName": "get_mobile",
"password": "NOTUSED"
}
}
}Success Response
json
{
"response": "{SYSTEM_SESSION_ID}",
"exception": null
}TIP
The app calls this lazily, only when a request needs a session and no user session is stored. It caches the id in memory for the rest of the run. You can do the same: call authenticateSystem once for anonymous/service calls, then reuse the id — but switch to the user session id as soon as you log in.
Log In with a PIN
Exchanges a device id + PIN for a session id. Used by the "quick login" / biometric unlock flow.
plaintext
POST /json/authentication
method: authenticatePINParameters
| Field | Type | Required | Description |
|---|---|---|---|
systemCredentials | object | YES | Fixed get_mobile block. |
deviceId | string | YES | Stable device identifier (iOS identifierForVendor). |
pin | string | YES | The PIN previously registered with createPIN. |
Request
json
{
"method": "authenticatePIN",
"params": {
"systemCredentials": {
"domain": "",
"userName": "get_mobile",
"password": "NOTUSED"
},
"deviceId": "{DEVICE_ID}",
"pin": "1234"
}
}Success Response
json
{
"response": "{SESSION_ID}",
"exception": null
}IMPORTANT
The PIN is sent as entered. Although the bundle contains authenticatePinTotp$ and createUserPinTotp helpers that would encode it with the SOA routine, neither has a call site in 5.1.20 — the live path is authenticatePin$ → authenticatePIN with the raw PIN. The only place the old encoding still runs is the one-time migration of a legacy auth_pin value. See SOA Barcode § PIN encoding.
Re-Authenticate a Session Token
Trades a
sessionTokenfor a fresh session id. Defined but unused in GET Mobile 5.1.20 — the app never calls it (the facade method has no call sites). Useful if you are implementing a web/SSO handoff that receives a token.
plaintext
POST /json/authentication
method: authenticateSessionTokenNOTE
Unlike the other authenticate* methods, this one does not flag useSessionId, so no session is injected; the sessionToken is the only credential it needs.
Request
json
{
"method": "authenticateSessionToken",
"params": {
"systemCredentials": {
"domain": "",
"userName": "get_mobile",
"password": "NOTUSED"
},
"sessionToken": "{SESSION_TOKEN}"
}
}Success Response
json
{
"response": "{SESSION_ID}",
"exception": null
}Get an Authentication Token
Exchanges the current session (user session if logged in) for a short-lived
session_tokenused by CBORD-hosted web pages — meal-plan change/purchase (link_in.php?session_token=…), the USAePay card page (add_card_mobile.php), and the Apple Pay page (applepay.php).
plaintext
POST /json/authentication
method: getAuthenticationTokenParameters
No business parameters. The app flags this useSessionId = true / useInstitutionId = false, so only sessionId is injected:
json
{
"method": "getAuthenticationToken",
"params": {
"sessionId": "{SESSION_ID}"
}
}response is the token string:
json
{
"response": "{SESSION_TOKEN}",
"exception": null
}IMPORTANT
This is not the session id and cannot be sent as params.sessionId. It only works as the session_token query parameter on the hosted pages. It also reflects whichever session was attached — before login that is the system session, which is why the hosted pages only offer patron features once a user session exists.
Get an External Authentication Token
Returns a token issued by an external identity system. GET Mobile uses this to obtain the OmniID JWT that authorizes mobile-credential (Apple Wallet / Google Wallet / HID) calls.
plaintext
POST /json/authentication
method: retrieveExternalAuthenticationTokenParameters
| Field | Type | Required | Description |
|---|---|---|---|
tokenType | null | YES | Always null in the app. |
externalSystem | string | YES | External system name. The app passes "OmniID". |
claimSet | null | YES | Always null in the app. |
sessionId | string | YES | User session (injected). |
institutionId | string | YES | Institution (injected). |
Request
json
{
"method": "retrieveExternalAuthenticationToken",
"params": {
"tokenType": null,
"externalSystem": "OmniID",
"claimSet": null,
"sessionId": "{SESSION_ID}",
"institutionId": "{INSTITUTION_UUID}"
}
}Success Response
json
{
"response": "{OMNIID_JWT}",
"exception": null
}The JWT is sent as Authorization: Bearer {OMNIID_JWT} to the partner services host. See Mobile Credentials.
Retrieve an Authorization Blob
Returns the opaque device authorization blob used by the partner services API for wallet provisioning.
plaintext
POST /json/authentication
method: retrieveAuthorizationBlobParameters
| Field | Type | Required | Description |
|---|---|---|---|
deviceModel | string | YES | Device model, e.g. iPhone15,2 or Android SDK built for x86. |
deviceOSVersion | string | YES | OS version, e.g. 18.1 / 8.0.0. |
sessionId | string | YES | User session (injected). |
Request
json
{
"method": "retrieveAuthorizationBlob",
"params": {
"deviceModel": "iPhone15,2",
"deviceOSVersion": "18.1",
"sessionId": "{SESSION_ID}",
"institutionId": "{INSTITUTION_UUID}"
}
}Success Response
json
{
"response": "{AUTHORIZATION_BLOB}",
"exception": null
}Retrieve a Patron Barcode Payload
Server-side equivalent of the offline barcode generator. Returns the encoded barcode for the session's patron.
plaintext
POST /json/authentication
method: retrievePatronBarcodePayloadParameters
| Field | Type | Required | Description |
|---|---|---|---|
sessionId | string | YES | User session. Explicitly passed, not injected. |
Request
json
{
"method": "retrievePatronBarcodePayload",
"params": {
"sessionId": "{SESSION_ID}"
}
}Success Response
json
{
"response": "{BARCODE_STRING}",
"exception": null
}TIP
The app prefers generating the barcode locally when the institution exposes soa.general.key, and only falls back to this method when offline generation is disabled. Both produce the same 22-character format. See SOA Barcode.
Request a Password Reset Email
Sends the institution's "forgot password" email. This is a separate service from
/json/authentication: it lives on/json/notification.
plaintext
POST /json/notification
method: resetPasswordNotification| Field | Type | Required | Description |
|---|---|---|---|
institutionId | string | YES | Institution id. Passed explicitly, not injected. |
userName | string | YES | The email address / username the patron enters. |
sessionId | string | YES | Session id. Passed explicitly. |
json
{
"method": "resetPasswordNotification",
"params": {
"institutionId": "{INSTITUTION_UUID}",
"userName": "[email protected]",
"sessionId": "{SESSION_ID}"
}
}The response is a boolean. A truthy value means the email was sent; the app then shows the "email sent" confirmation. Any falsy value or error shows Could not sent the reset email. Please try again in a few minutes. (the typo is in the app).
NOTE
The app calls this while only holding a system session (obtained via authenticateSystem), not a user session. The username is the field the institution configured, usually the email address.
The screens use content category patron-ui.forgot-password.
Session Lifetime and Renewal
- Session ids are opaque strings. Store them exactly as returned.
- The app caches the user session in device storage under
get_sessionId; the system session is memory-only and is dropped when the process dies or on logout. - Error codes that mean "the session is gone":
4001|Session not foundand4002|No user associated with this session, plus theNoSuchSessionException/NoUserInSessionExceptionexceptions they map to. - On expiry the app does not silently mint a replacement. Its error interceptor calls
handleInvalidSession(), which debounces duplicate failures and runs a lock/re-auth flow (vault/biometric/PIN, then login) before rethrowing the error. authenticatePINsessions are re-created fromdeviceId+ PIN without requiring the user's password again.getAuthenticationTokentokens are for hosted pages only and should be treated as disposable; they are not a substitute for a session id.