docs
/
AppEngine API

User authentication

Operator sign-in, invitations, password management and session endpoints.

Users are the operators of a tenant. Everything here lives on UsersController, mounted as @Controller(['profile', 'user']) — so every path below also answers under /user/….

Password sign-in

POST/profile/signinNo auth

Also /profile/user/signin, /user/signin, /user/user/signin.

{ "email": "[email protected]", "password": "…" }

Send orgid for a known tenant; the current staff sign-in also supports organization discovery when it is omitted. Multiple possible 200 responses — see Sign-in outcomes. Only a completed session contains a token.

Bad credentials are 400 Invalid username or password, recorded as a failed login activity. A blocked device fingerprint is 403 regardless of credentials.

Temporary passwords

A user signing in with a temporary password — stored hashed in resetToken alongside a temporaryPassword flag — gets no session:

{ "requiresPasswordChange": true, "message": "Temporary password used. Please set a new password.", "userId": "…", "email": "…" }

POS passcode and NFC

POST/profile/signin/passcodeNo auth

Fast sign-in for point-of-sale, keyed on the employee id.

{ "employeeId": "E-1042", "pin": "482913", "cardUid": "04A2B3C4D5" }
FieldTypeDescription
employeeId requiredstringThe employee id. An NFC card carries only this value.
pinstringSix digits. Required or not depending on the org's passcode-vs-instant setting.
cardUidstringThe card's hardware UID when signing in by tap. Validated against the registered card list.
This path deliberately skips the 2FA and new-device challenges — a shared terminal would otherwise be unusable.

Managing the credentials:

ActionEndpoint
Set or change a passcode, link an employeeIdPOST /profile/…/passcode (set)
Remove passcode loginremove-passcode handler
Register / revoke an NFC cardcard registry handlers

A user may always manage their own quick-login credentials. Doing it for someone else requires RootSystem, RootAdmin, ConfigAdmin, System or Owner; otherwise 403.

Session

GET/profile/whoamiNo auth
GET/profile/who-isNo auth
POST/profile/signoutNo auth
POST/profile/user/refreshNo auth
POST/profile/session-accessJWT
GET/profile/system-orgsNo auth

whoami can return Anonymous User; it is not proof of protected record access. who-is can include token details, so do not expose its output in logs or recordings. The current signout handler is empty; clear the client session locally and use the appropriate session/device controls when server-side revocation is required. Public handlers can still require tenant context in middleware.

Invitations

Users are invited, not self-registered.

POST/profile/user/invite/sendJWT
POST/profile/user/invite/resend/:invitationIdJWT
POST/profile/user/invite/validateNo auth
POST/profile/user/invite/completeNo auth

Invitations are user_invitation records. validate confirms a token before showing the form; complete sets the password and activates the account.

Profiles

GET/profile/user/profile/:emailOrUsernameJWT
POST/profile/user/:userId/metaJWT
DELETE/profile/user/delete/:emailOrUsernameJWT
DELETE/profile/user/selfJWT

Reading or writing your own profile bypasses role checks — JwtAuthGuard compares the target record's sk with the caller's before any decorator is consulted.

/profile/user/self is self-service account deletion, distinct from an admin deleting someone.

GET/profile/user/magic-linkNo auth
POST/profile/user/magic-link/redirectNo auth
GET/profile/magic-linkNo auth
POST/profile/magic-link/redirectNo auth
GET/profile/code/:emailNo auth

A magic-link token is a short-lived JWT whose payload is { clientHost, email, expires } — signed the same way as a session token, so it verifies through the same machinery.

Shared-site access

GET/profile/user/shared-site-auth/:tokenNo auth

Exchanges a share token for access — the share block on BaseModel, with its optional passcode and expiry.

Application registration

For client apps that need their own identity:

POST/profile/app/registerJWT,
POST/profile/app/keyNo auth
POST/profile/app/challengeNo auth
POST/profile/app/attestNo auth
PUT/profile/app/:id/identityJWT,
POST/profile/app/:id/debug-tokenJWT,
DELETE/profile/app/:id/debug-token/:tokenIdJWT,
GET/profile/app/:id/signinsJWT,
POST/profile/validate-app-keyJWT,

An app credential is a user in the System group with userType: 'app'; its App ID is the username. Every route that takes appId also accepts the credential's record id (sk). A System login made with an email (older sites' chat logins) is not an app credential and cannot sign in by app/attest.

The app-key exchange takes { "appId": "acme-mobile", "secret": "…" } and optionally domain; the current controller does not read the key field also sent by the clients. Store its returned token as the application token, separate from the staff or customer session. App registration is an administrator operation, not anonymous signup.

The secret exchange is for servers. A phone app ships only the org ID and App ID: it asks app/challenge for a one-use nonce and proves it is the genuine build at app/attest with Apple App Attest, Google Play Integrity or a debug token, and gets a 1-hour app token. A web page signs in at app/attest with platform: "web" and the page's domain instead: no challenge, the domain must be one of the app's Allowed domains (web.domains) and match the browser's Origin, and it works whatever the check is set to. The app credential's check (off, monitor, enforce, set through app/:id/identity) decides which ways in work; on enforce, app/key answers 401 with reason: "secret_refused". A revoked app credential's tokens are refused on every request (app_revoked). See Phone apps without a secret for the requests, the identity to register and the refusal reasons.

POST/profile/user/refresh

Staff refresh also accepts refreshToken; customer refresh currently reads refresh_token. Save the new token pair after refresh. When a sign-in returns requiresTwoFactor, verify the challenge first; an HTTP success without a token must not create a session.

Global login

POST/profile/global-loginNo auth

Signs in across orgs rather than against one tenant. Pair with GET /repository/org/user/:email to build an org switcher.

Guest access

POST/profile/guest/authNo auth

Issues a token for an anonymous guest customer — enough to hold a cart or a draft booking before the visitor commits to an account.

Only a signed-in app makes guests: send the app's own token (from app/attest or app/key) as Authorization: Bearer, with orgid. The body needs email or phone. The appId header is optional and, when sent, must name the app the token belongs to (App ID or record id). Without this app's token the answer is 401 with code: "app_token_required". The response carries guest, token and refreshToken.