> For the complete documentation index, see [llms.txt](https://docs.makapay.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.makapay.io/point-of-sale-pos/sessions.md).

# Sessions & Authentication

POS businesses 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 business 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 business** --> Error: "Not assigned to this business"

## 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 business, 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 businesses 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 business Location
* 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 business
* 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 business (via business deactivation)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
