Skip to content

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 exceptionMeaning
4001|Session not foundThe session id is unknown or expired
4002|No user associated with this sessionThe session is valid but has no patron/guest attached (a system session)
ArtifactCreated byScopeLifetimePersisted in the app?
System sessionauthenticateSystemInstitution/service. No user.One app runNo — in-memory field systemSessionId
User sessionauthenticateUser / authenticateGuestUser / authenticatePINOne logged-in patron or guestUntil the server expires itYes — storage key get_sessionId
Session tokengetAuthenticationTokenA hosted-web handoff derived from the current sessionShort-livedOnly 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 to null); 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 the guestUser flag set on the user record.
  • authenticatePIN mints a new user session from deviceId + 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:

PrioritySourceWhen
1params.sessionId already presentThe caller passed an explicit id (used by a few pre-login calls).
2Cached user session (get_sessionId)Whenever somebody is logged in.
3System sessionNo 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.

FieldTypeValuesEffect in the app
institution.authenticationSystemTypenumber1 HOSTED, 2 LDAP, 3 SSO_GENERIC, 4 CAS, 5 OKTA, 6 OKTA_EXTLabels/affordances on the in-app login form
institution.authenticationInfo.authenticationTypestring"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 ​

  1. The app builds the institution's login URL from the environment's site_url and the institution's shortName:

    plaintext
    {site_url}/{shortName}/full/login.php?mobileapp=1

    For production Northeastern that is https://get.cbord.com/northeastern/full/login.php?mobileapp=1. This is the same page the wrapper's /api/v2/login uses as its RelayState.

  2. It opens that URL in an in-app browser (_blank, WKWebView on iOS, cache and cookies cleared) and watches every loadstart event.

  3. When the URL contains mobileapp_login_validator.php, the app takes the query string and uses its value as the user session id:

    js
    sessionId = url.split("?")[1].split("=")[1];
  4. 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: authenticateUser

Parameters ​

FieldTypeRequiredDescription
systemCredentialsobjectYESFixed get_mobile block above.
userCredentials.userNamestringYESPatron username (often the campus card number or directory id).
userCredentials.passwordstringYESPatron password.
userCredentials.domainstringYESUsually "".
userCredentials.institutionIdstringYESUUID 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 the authenticateGuestUser method name.

plaintext
POST /json/authentication
method: authenticateGuestUser

Parameters 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: authenticateSystem

Request ​

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: authenticatePIN

Parameters ​

FieldTypeRequiredDescription
systemCredentialsobjectYESFixed get_mobile block.
deviceIdstringYESStable device identifier (iOS identifierForVendor).
pinstringYESThe 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 sessionToken for 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: authenticateSessionToken

NOTE

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_token used 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: getAuthenticationToken

Parameters ​

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: retrieveExternalAuthenticationToken

Parameters ​

FieldTypeRequiredDescription
tokenTypenullYESAlways null in the app.
externalSystemstringYESExternal system name. The app passes "OmniID".
claimSetnullYESAlways null in the app.
sessionIdstringYESUser session (injected).
institutionIdstringYESInstitution (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: retrieveAuthorizationBlob

Parameters ​

FieldTypeRequiredDescription
deviceModelstringYESDevice model, e.g. iPhone15,2 or Android SDK built for x86.
deviceOSVersionstringYESOS version, e.g. 18.1 / 8.0.0.
sessionIdstringYESUser 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: retrievePatronBarcodePayload

Parameters ​

FieldTypeRequiredDescription
sessionIdstringYESUser 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
FieldTypeRequiredDescription
institutionIdstringYESInstitution id. Passed explicitly, not injected.
userNamestringYESThe email address / username the patron enters.
sessionIdstringYESSession 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 found and 4002|No user associated with this session, plus the NoSuchSessionException / NoUserInSessionException exceptions 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.
  • authenticatePIN sessions are re-created from deviceId + PIN without requiring the user's password again.
  • getAuthenticationToken tokens are for hosted pages only and should be treated as disposable; they are not a substitute for a session id.