Antylogic
DemoApp login

399 operational guides

Docs sections
DocsPOS
Device

Authenticate by Card

Use an existing staff card credential to select the POS operator for Harbor Soho before working in the active service. In the GB demo, the example operator is Olivia Hart on the current TPV terminal. This identifies the operator for POS activity only; it does not sign the person into Antylogic as an app user.

In this article

Use this guide when Harbor Soho requires card-based staff identification before the POS workspace opens. The card check resolves the staff member for the active service on the current terminal.

Keep the terminal id in the POS route so terminal-scoped credentials are evaluated correctly, and never show a real or reusable card code in screenshots, videos, examples, logs or support notes.

Before you start

  • The operator is signed in to Harbor Demo Group and has `tpv:use` access to Harbor Soho.
  • A Harbor Soho service session is already active; the POS card prompt only opens after an active session exists.
  • Employee access for the POS resolves to `card`, either from TPV settings or a terminal capability override.
  • The POS is opened with `terminalId=${TPV_TERMINAL_ID}` for the current terminal.
  • Olivia Hart, or the staff member used for the capture, has an active `card` staff TPV credential for Harbor Soho that is allowed for the current terminal or available to all terminals.
  • The operator has the physical card or disposable documentation-only card code to scan or type. The card code is secret and is not returned by staff credential list or detail screens.

Instructions

  1. 1.

    Open the POS on the current terminal

    Open `antylogic://${ORG_ID}/${LOCATION_ID}/tpv?tab=floor&terminalId=${TPV_TERMINAL_ID}`. The POS page reads the current terminal and keeps the terminal id in the route so credential filtering can stay terminal-aware.

  2. 2.

    Wait for the card access prompt

    When the active service is open and employee access mode is `card`, the POS keeps the workspace hidden and opens the employee selection modal with the card-code input. Active card credentials are listed for the current terminal when a terminal id is present.

  3. 3.

    Scan or type the card code

    Scan the staff card or type the documentation-only card code into the prompt. Blank codes are ignored by the frontend, and the submitted value is trimmed before authentication.

  4. 4.

    Validate the card

    Select the card validation action. The POS sends `{ credential_code: string, terminal_id?: string }` to `POST /api/app/{orgId}/{locationId}/tpv-auth/card`. Use typed or scanned input as the documented path; do not rely on card tile selection until it has been validated at runtime.

  5. 5.

    Continue as the selected POS employee

    When the card matches an active credential, Antylogic returns the linked staff member, clears the card-code input, closes the modal and shows the POS workspace with the selected employee in the header, for example Olivia Hart.

  6. 6.

    Check credential setup if access fails

    If the card is not accepted, confirm the staff TPV credential exists, is active, is type `card`, belongs to Harbor Soho and is allowed for the current terminal. Creating or editing that credential is setup work and requires `tpv:manage`.

Validations and limits

  • The POS screen itself requires `tpv:use`; the backend card resolver also accepts `tpv:card-auth` or `tpv:manage`.
  • `POST` is the only accepted method for `/tpv-auth/card`, and the auth subtype must be `card` or `pin`.
  • Selector authentication is not exposed through `POST /tpv-auth/selector`; selector mode is handled by the UI and credential list.
  • The request body must be valid JSON and may include `credential_code` and `terminal_id`.
  • The card code is trimmed, must be non-empty and is matched exactly after trimming; do not document card codes as case-insensitive.
  • Only active staff TPV credentials for the current location and credential type `card` are considered.
  • When `terminal_id` is supplied, the credential must have an empty `allowed_terminal_ids` list or include that terminal. If terminal id is omitted, the resolver does not apply terminal filtering.
  • Card credential codes are secret: they are hashed at rest and are not serialized in staff credential API responses or logs.
  • A successful match updates `last_used_at` on the credential best-effort and may rehash a legacy plaintext value, but the operator selection still succeeds if that timestamp update fails.
  • This action selects the POS operator only. It does not create an app login session, issue tokens, create credentials or open a service session.

Expected result

The Harbor Soho POS workspace opens for the active service with the resolved staff member selected, such as Olivia Hart. The staff card code stays hidden, and the app session remains the original signed-in Antylogic user.

Related articles