# Users and identity

> Act for each of your customers with their own device, session, memory, email inbox, phone number and vault of sign-in details.

Most real tasks are done for someone: your customer, a patient, a tenant. Give each task the `user` it acts for, with your own id for that person. Hapti then keeps a stable identity for them from task to task, so sites see the same person coming back instead of a new robot each time.

```json
{ "url": "https://portal.example.com", "goal": "Download my last statement.", "user": "customer_42" }
```

You do not need to create the person first: the first task with a new `user` creates it. Create it explicitly to set their country, language and time zone in advance:

```json
{
  "object": "user",
  "id": "customer_42",
  "name": "Ana Silva",
  "created_at": "2026-11-22T18:40:56.163Z",
  "mandate": null,
  "session": null,
  "device": {
    "locale": "pt-PT",
    "timezone": "Europe/Lisbon",
    "country": "pt",
    "country_set": true,
    "since": "2026-11-22T18:40:56.165Z"
  },
  "limits": null,
  "accounts": []
}
```

## What a person keeps

| What | Default with a user | Turn it off |
| --- | --- | --- |
| **Device**: one browser profile, language, time zone and country | Always | |
| **Session**: cookies and sign-ins saved at the end of a task and restored at the next | On | `"keep_session": false` |
| **Memory**: lasting facts the agent learns about the person, never secrets | On | `"memory": false` |
| **Email inbox**: an address the agent can give sites to receive codes and links, read by itself | On | `"mailbox": false` |
| **Phone number**: receives the text messages sites send, when you gave the person one | On | `"phone": false` |
| **Stored accounts**: sign-in details the agent types without the model seeing them | When listed in `accounts` | |

## Stored accounts

Save the person's sign-in details for a site in the vault. They are sealed, and the agent types them into the browser without the model ever reading them.

```bash
curl -X PUT https://api.hapti.dev/v1/users/customer_42/accounts/insurer \
  -H "Authorization: Bearer $HAPTI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"origin": "https://portal.example.com", "username": "ana.silva", "password": "...", "totp_secret": "JBSWY3DPEHPK3PXP"}'
```

Then name the account in a task:

```json
{ "url": "https://portal.example.com", "goal": "Download my last statement.", "user": "customer_42", "accounts": ["insurer"] }
```

With `totp_secret`, the agent also fills the two-factor code. Secrets are never returned by the API and never written to logs.

### Connect links

You may prefer never to hold the person's passwords at all. Create a connect link: a page, with your brand, where the person types their own details. You never see them.

```bash
curl https://api.hapti.dev/v1/users/customer_42/connect \
  -H "Authorization: Bearer $HAPTI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"accounts": [{"account": "insurer", "origin": "https://portal.example.com"}]}'
```

The answer holds a `url` to send to the person, and an `expires_at`. You receive a `user.account_connected` event once they are done.

## Mandates

A mandate records what the agent may do for the person, and how they agreed to it. It is kept with the person and with the proof of each task.

```bash
curl https://api.hapti.dev/v1/users/customer_42/mandate \
  -H "Authorization: Bearer $HAPTI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scope": "Declare insurance claims and download invoices", "given_by": "Ana Silva, in the app on 2026-11-20"}'
```

Add `sites` to limit it to some addresses and `until` to make it end. When a task must wait for a human decision before committing the person, create it with `"approval": "required"`.

## Limits per person

Protect yourself from a runaway loop or an abusive end user with limits per person:

```bash
curl -X PATCH https://api.hapti.dev/v1/users/customer_42 \
  -H "Authorization: Bearer $HAPTI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limits": {"tasks_per_day": 20, "cents_per_month": 500}}'
```

A task over a limit is refused with a clear error. Send `"limits": null` to remove them.

## Email and phone

- [`POST /v1/users/{user}/inbox`](/docs/api-users#open-an-email-inbox) opens a lasting address for the person, and [`GET /v1/users/{user}/emails`](/docs/api-users#list-received-emails) lists what it received.
- [`POST /v1/users/{user}/phone`](/docs/api-users#give-a-phone-number) gives the person a real number that receives texts. It needs a live key and is paid each month from your credit.

## Forget a person

[`DELETE /v1/users/{user}`](/docs/api-users#forget-a-person) erases the session, memory, stored accounts, mandate, inbox and received messages of the person. Use it when your customer closes their account or asks to be forgotten.
