Authentication
How merchant sessions, passkeys, two-factor authentication, and team invites work.
Globagift authentication is session-based (cookie auth), not API keys. This page explains the concepts; for how individual BFF endpoints check a session against a specific permission, see each endpoint in the API reference.
Signing in
A merchant user can sign in with:
- Email and password. Requires a verified email address (verification emails are sent on sign-up, and again on sign-in if not yet verified).
- Magic link. A one-time sign-in link emailed to the user, no password needed.
- Google or GitHub, if your account was set up to use one of these (social sign-in is enabled per-deployment, not guaranteed to be available).
A successful sign-in creates a session cookie valid for 7 days. The portal sends a "new device" email alert when a session is created from a previously unseen device or location.
Passkeys
Accounts can register a passkey (WebAuthn/FIDO2: device biometrics, a security key, or a platform authenticator) as a passwordless, phishing-resistant sign-in method, in addition to or instead of a password.
Two-factor authentication
Accounts can enable TOTP-based two-factor authentication as an additional sign-in step on top of a password or other primary method.
Forgotten password
A password reset emails a time-limited link (expires after 60 minutes). Completing a reset revokes all of the account's existing sessions, signing out any other active devices.
Team invites
Adding a teammate is a multi-step, OTP-verified process rather than a
direct "add user" API call (the relevant BFF endpoint,
POST /api/bff/merchant/users, intentionally always rejects direct adds;
see Merchant + team).
The real flow is:
Request an invite
An organization admin enters the invitee's name, email, and role in the dashboard. The portal emails a one-time verification code to the admin's own email address, not the invitee's, as a confirmation step before any invite email goes out.
Confirm the code
The admin enters the code. Up to 5 incorrect attempts are allowed before the invite request must be restarted; the code itself expires after 10 minutes. Once confirmed, the invitee receives an email with a one-time portal join link (valid for 7 days).
Invitee joins
The invitee follows the link, then signs in or creates an account using the same email address the invite was sent to. If they're already signed in with a different email, or their account already belongs to a different merchant, joining is blocked with a clear explanation rather than silently reassigning their account.
Account linked
Once linked, the invitee's account is attached to the merchant with the
role chosen in step 1 (Admin, Full access, or Viewer). The one-time
join link cannot be reused.
Last admin protection
A merchant must always have at least one admin-capable team member. The dashboard (and the underlying role-change endpoint) blocks demoting the last one, and blocks an admin from changing their own role from this flow. See Merchant + team: change a team member's role.
Permissions
Once signed in, what a team member can see and do is governed by their
team role (Admin, Full access, Viewer), mapped to specific
permissions per dashboard area (for example, POS access, gift card
management, reports). Admin accounts (a separate, internal-only role from
team roles) bypass per-area permission checks entirely. Each endpoint in
the API reference lists the specific permission it
requires.