Concepts

Security and sign-in

How your people sign in to the portal, what the API lets you read of it, the one thing it lets you do, and what each person can only do themselves.

How people sign in

The API is used with tokens. The portal is used by people: your admins and sellers (see Sellers and attribution). A person signs in with:

  • A password and two-factor sign-in. Two-factor sign-in means a second step after the password: a six-digit code from an authenticator app on the person's phone. Everyone sets it up at their first sign-in, and gets recovery codes to keep for the day the phone is gone. A recovery code signs in once, in place of the code from the phone.
  • Or a passkey. A passkey is a key kept by the person's device, unlocked with a fingerprint, a face or a PIN. It signs in on its own, without the password or a code. A person adds passkeys after they have set up two-factor sign-in.

A seller shows where each person stands: two_factor (true once it is set up) and passkeys (how many they have). These two fields and last_login_at are only in the answer when the token has the security:read ability.

What the API does

You want to Over the API Ability
See who can sign in, and how List who can sign in security:read
Read the sign-in log List the sign-in log security:read
Help someone who lost their phone Reset two-factor sign-in sellers:write and admins:write
Keep someone out Change a seller with { "disabled": true } sellers:write, plus admins:write for an admin
Let someone in Add a seller or Invite a seller: they choose their own password from the emailed link sellers:write, plus admins:write for an admin

Everything else about signing in is done by the person, in the portal. See What only the person can do.

Who can sign in

List who can sign in gives the people who can sign in now: those who have a password and are not disabled. Invited people who have not chosen a password yet, and sellers without a login, are left out.

cURL
curl https://partners.monotree.com/api/v1/security/people \
  -H "Authorization: Bearer $MONOTREE_TOKEN"
JSON
{
  "object": "list",
  "data": [
    {
      "object": "security_person",
      "seller": { "id": "sel_5", "name": "Emma Dubois", "external_ref": "usr_20503" },
      "email": "emma@acme.example",
      "role": "seller",
      "two_factor": true,
      "passkeys": 0,
      "last_sign_in": { "at": "2026-11-14T12:41:59Z", "device": "Chrome on macOS", "ip": "203.0.113.7", "via": "password" },
      "failed_7d": 0,
      "dormant": false
    }
  ],
  "has_more": true,
  "next_cursor": "6Yb0mT9wQ3F7ImlkIjo1fQ"
}
Field Means
seller The person, as every answer names a seller: Monotree's ID, name and your reference
email, role The address they sign in with, and admin or seller
two_factor Whether two-factor sign-in is set up
passkeys How many passkeys they have
last_sign_in When, from what and from where they last signed in. null for someone who never signed in. via is password or passkey. device, ip and via are null when the sign-in is older than the sign-in log (180 days)
failed_7d Wrong passwords, wrong two-factor codes and lockouts in the last 7 days
dormant true after 90 days without a sign-in; for someone who never signed in, 90 days after they were added. A dormant account is worth disabling

The list is ordered newest first by when the person was added, and paged with limit and cursor as every list. It takes no filters.

The sign-in log

List the sign-in log gives every sign-in, sign-out, wrong try and change to how someone signs in, newest first. A line is kept 180 days.

cURL
curl "https://partners.monotree.com/api/v1/security/events?seller=external_ref:usr_20503&created_after=2026-11-14T12:00:00Z" \
  -H "Authorization: Bearer $MONOTREE_TOKEN"
JSON
{
  "object": "list",
  "data": [
    {
      "id": "sev_83",
      "object": "security_event",
      "type": "two_factor.confirmed",
      "label": "Two-factor sign-in turned on",
      "denied": false,
      "seller": { "id": "sel_5", "name": "Emma Dubois", "external_ref": "usr_20503" },
      "device": "Chrome on macOS",
      "ip": "203.0.113.7",
      "created_at": "2026-11-14T12:43:36Z"
    },
    {
      "id": "sev_82",
      "object": "security_event",
      "type": "login",
      "label": "Signed in",
      "denied": false,
      "seller": { "id": "sel_5", "name": "Emma Dubois", "external_ref": "usr_20503" },
      "device": "Chrome on macOS",
      "ip": "203.0.113.7",
      "created_at": "2026-11-14T12:41:59Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
Parameter Gives
show=denied Attempts that did not get in: login.failed, login.lockout, two_factor.failed
show=changes Changes to how someone signs in: password.reset, password.changed, two_factor.confirmed, two_factor.disabled, two_factor.reset, two_factor.recovery_code_used, two_factor.recovery_codes_generated, passkey.added, passkey.removed
show=all Everything. The same as leaving show out
seller One person: sel_5 or external_ref:<your reference>. An unknown person answers 404
after Lines later than a time, to fetch only what is new

Page through it with limit and cursor, as every list.

type is one of these. label is the same thing as an English sentence for a person; act on type.

type Means
login Signed in. The label is "Signed in with a passkey" when a passkey was used
logout Signed out
login.failed Wrong password
login.lockout Too many wrong tries: five in a minute stop further tries for a minute
two_factor.failed Wrong two-factor code
password.reset Chose a new password with the "forgot password" link emailed to them
password.changed Changed their password on their own account page
two_factor.enabled Started setting two-factor sign-in up. It is not on yet
two_factor.confirmed Finished setting it up: two-factor sign-in is on
two_factor.disabled Two-factor sign-in was turned off: by a reset, or because the person is moving it to a new phone
two_factor.reset An admin or the API reset it. For the API, the label names your token and device and ip are those of the call
two_factor.recovery_code_used Signed in with a recovery code
two_factor.recovery_codes_generated Got a new set of recovery codes
passkey.added Added a passkey
passkey.removed Removed one of their passkeys

device is the browser and system in a few words, or Unknown device.

What the log leaves out: a wrong password for an email address that belongs to none of your people, and passkeys removed by a reset (the two_factor.reset line stands for them).

Someone lost their phone

A person who lost their phone and their recovery codes cannot sign in. An admin resets them on the Sellers or Security page of the portal, or your system does it:

cURL
curl -X POST https://partners.monotree.com/api/v1/sellers/external_ref:usr_20503/reset-two-factor \
  -H "Authorization: Bearer $MONOTREE_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

The call takes no body. The answer is the seller, with "two_factor": false and "passkeys": 0. The reset:

  • turns their two-factor sign-in off and makes their recovery codes useless, so they set it up again the next time they sign in with their password;
  • removes their passkeys, as the lost phone may be the device that held one;
  • signs them out everywhere;
  • emails them that it was done through the API, with the name of your token, and writes two_factor.reset in the sign-in log (after two_factor.disabled when two-factor sign-in was on).

Their password stays as it is. For someone with nothing to reset the call answers 200, changes nothing and sends no email.

The call needs sellers:write, and admins:write as well when the person is an admin or has chosen a password, which is everyone with something to reset; without them the answer is 403 with the type insufficient_ability.

What only the person can do

There is no endpoint for any of these. Each person does them in the portal, on their own account page unless said otherwise:

  • Choose their first password, from the link in the invitation.
  • Change their password (it takes the current one), or reset a forgotten password with the "forgot password" link on the sign-in page. A password has at least 10 characters, with letters and digits.
  • Set two-factor sign-in up, at their first sign-in and again after a reset, and move it to a new phone.
  • Get new recovery codes. The codes are shown once when two-factor sign-in is set up, and again only when new ones are made.
  • Add and remove passkeys.
  • Choose the language of the portal and of the emails they get.

The portal asks for the password again before a sensitive step, such as setting two-factor sign-in up, getting new recovery codes, moving to a new phone, adding or removing a passkey, or an admin resetting someone's two-factor sign-in. Once typed, the password is not asked for again for 15 minutes.

A person can also change their own name and email address there; a token can change those over the API too, with Change a seller: the name with sellers:write, the email address of someone who signs in with admins:write as well. Whoever changes it, the old address gets an email, the person is signed out everywhere else, and a password-reset link asked for before stops working.

So the API never shows or sets a password, a two-factor secret, a recovery code or a passkey. It cannot turn two-factor sign-in on for someone, add or remove a single passkey, sign someone out without resetting or disabling them, or send a "forgot password" email. Two-factor sign-in cannot be switched off for a person or for your company.

Sandbox

Test sellers never sign in (see Sandbox sellers). With a sandbox token (mpt_test_…):

To see real lines, read the lists with a live token: both calls only read.