# Sessions & Authentication

POS terminals use **PIN-based authentication** -- no email, no password, no account needed. Cashiers log in with a numeric PIN and get a 15-minute session.

## Login Flow

> 1. Cashier opens the terminal URL
> 2. Numeric keypad appears (digits only)
> 3. Cashier enters their 8+ digit PIN
> 4. System checks if the PIN matches an allowed cashier
>    * **Match** --> Session created, payment screen appears
>    * **Wrong PIN** --> Error: "Invalid PIN"
>    * **Not allowed on this terminal** --> Error: "Not assigned to this terminal"

## Session Lifetime

| Event                 | What Happens                              |
| --------------------- | ----------------------------------------- |
| **Login**             | Session starts with 15-minute timer       |
| **Any activity**      | Timer resets to 15 minutes (touch/extend) |
| **< 60 seconds left** | Warning message appears                   |
| **Timer expires**     | Auto-logout, cashier must re-enter PIN    |
| **Manual logout**     | Session ends immediately                  |

Sessions are activity-based: as long as the cashier is actively using the terminal, the session stays alive. 15 minutes of **inactivity** triggers auto-logout.

### Session Lifecycle

> **Logged Out** --> Enter PIN --> **Active** (15 min timer)
>
> While **Active**:
>
> * Any activity --> timer resets to 15 min
> * Less than 60 seconds left --> **Warning** state
> * Timer hits zero --> back to **Logged Out**
> * Manual logout --> back to **Logged Out**
> * Merchant deactivates cashier --> back to **Logged Out**
> * Merchant resets PIN --> back to **Logged Out**

## Why PIN-Only?

POS terminals are designed for in-store use where:

* Multiple cashiers share the same device
* Quick login/logout is essential
* No email or account setup should be required for staff
* The merchant manages all cashier credentials from the dashboard

## Session Security

* Session tokens are cryptographically random (32 bytes)
* Tokens are hashed before storage (SHA-256) -- the raw token only exists on the client
* Stored as an httpOnly secure cookie
* Expired sessions are automatically cleaned up

## What Cashiers See

After login, the cashier sees:

* Their name and the terminal name
* A countdown timer showing remaining session time
* The payment creation interface
* A logout button

## Multiple Sessions

* A cashier can only have one active session per terminal
* If a cashier logs in on a second device, both sessions are valid until they expire
* Merchants can force-end all sessions for a cashier (via PIN reset or deactivation)
* Merchants can force-end all sessions on a terminal (via terminal deactivation)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.makapay.io/point-of-sale-pos/sessions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.