Docs Sign in Get a key

Docs / Guides

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

WhatDefault with a userTurn it off
Device: one browser profile, language, time zone and countryAlways
Session: cookies and sign-ins saved at the end of a task and restored at the nextOn"keep_session": false
Memory: lasting facts the agent learns about the person, never secretsOn"memory": false
Email inbox: an address the agent can give sites to receive codes and links, read by itselfOn"mailbox": false
Phone number: receives the text messages sites send, when you gave the person oneOn"phone": false
Stored accounts: sign-in details the agent types without the model seeing themWhen 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.

Terminal
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.

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.

Terminal
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.

Terminal
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:

Terminal
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

Forget a person

DELETE /v1/users/{user} 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.