Password Recovery

Password recovery is a second way into an account, and a weaker one than the sign-in form: whoever controls the mailbox or the SIM gets the account without the password and without a step-up login. POST /v2/recoveries/assess answers one question at each step of a recovery: is this recovery risky enough to ask for more proof, to delay, or to review by hand? You get a recommendation — allow, challenge, hold, review or deny — with the reasons behind it.

We recommend; you act. Tracio does not block a recovery, does not send emails or SMS, does not issue reset tokens and does not touch the password: your backend asks us, gets the recommendation, and decides itself. The one thing Tracio does by itself is revoking the account's trusted devices after you report that the recovery was executed (see Outcome).

Base URL: https://api.tracio.ai. The routes live under /v2, the snake_case version of the Data API: every key in the request, the response and the error body is snake_case. Authorization is the same secret key as for the rest of the Data API (see data-api.md).

What your app / IdP does

Tracio gives a recommendation and a record. Everything below stays with your application or your identity provider; none of it is done for you:

• Show one and the same answer on the reset form — the same text, the same HTTP status and the same response time, whether the login exists or not. Show it before and regardless of what assess says, and do not wait for assess in the request that renders it (see Limits). The form must never tell a visitor that an account exists.
• Generate, hash and expire the reset token. Tracio never sees the token, the code or the password, and the request has no field for them.
• Send the emails and the SMS. On deny the message is simply not sent, and the form still answers as it does for everybody else.
• Run the step-up on challenge — a second factor, or any proof you trust more than the mailbox alone.
• Delay the execution on hold and notify the old contacts. Tracio returns the time until which to wait (hold.until, 24 hours after the first hold) and blocks nothing: the delay is yours to enforce.
• Review by hand on review — your own operator looks at the case before the password is written.
• Write the new password.
• End the user's sessions in your system.
• Notify the user after the reset, on the old and the new contact.
• Send the outcome to POST /v2/recoveries/{recovery_id}/outcome — it closes the loop and, for executed, triggers the revoke of the trusted devices.

1. Assess a stage

A recovery has two stages, and you assess each of them with the same recovery_id:

• requested — the user asked for a reset; call it before the email or the SMS is sent.
• completed — the token is accepted and the new password is not written yet.

curl -X POST https://api.tracio.ai/v2/recoveries/assess \
     -H "Authorization: Bearer $TRACIO_SECRET_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "recovery_id": "rec-8c1f",
       "stage": "requested",
       "reason": "forgot",
       "channel": "email",
       "request_id": "0f6c2d3a-91b4-4c1e-8a57-3b9d2e1f4a60",
       "identifier": "Alice@example.com",
       "contact_changed_at": "2026-10-17T09:30:00Z"
     }'

Request body. An unknown key answers 400 invalid_request.

There is no field for a token, a password or a one-time code, and you must not put one into any field.

Response

{
  "recovery_id": "rec-8c1f",
  "stage": "requested",
  "reason": "forgot",
  "channel": "email",
  "state": "assessed",
  "not_assessed_reason": null,
  "recommendation": "hold",
  "reasons": ["recent_contact_change"],
  "hold": {
    "until": "2026-10-18T12:00:00Z",
    "released_at": null,
    "released_by": null
  },
  "device": {
    "device_ref": "7978151c54e94838",
    "new_device": false,
    "trusted": false,
    "first_seen_at": "2026-10-15T12:00:00Z",
    "last_seen_at": "2026-10-17T10:00:00Z"
  },
  "travel": null,
  "ato": null,
  "self_exclusion": null,
  "location": {"city": "Berlin", "country": "DE"},
  "velocity": {"account_1h": 1, "device_1h": null, "network_1h": null},
  "assessed_at": "2026-10-17T12:00:00Z",
  "calculation_time": 41,
  "idempotent_replay": false
}

The response has no user_id, no identifier and no "account found" flag: the set of keys is the same with and without user_id (see Same response with and without an account).

A visit that is not found (request_id unknown, for example a script posting to your form without the SDK) is not an error: the answer is state: "not_assessed" with not_assessed_reason: "visit_not_found". The recommendation is then built from the facts that do not need a visit — recovery_velocity_account and recent_contact_change — and is null when neither fired. A script that brute-forces the form without the SDK is therefore still caught by login.

Policy

The strongest recommendation wins: deny > review > hold > challenge > allow. Without a user_id there are no account facts (history, trust, travel, ATO, self-exclusion): the bot check, the velocity counters and recent_contact_change decide.

deny is only for a bot at stage requested. A self-excluded account does not raise the recommendation: it still cannot sign in, because /v2/logins/assess answers deny for it. review is only for a link to a self-excluded account.

Reason codes

The order of reasons is fixed: trusted_device, first_device, new_device, ato_alert, impossible_travel, impossible_travel_anonymized, self_excluded, self_excluded_link, bot_traffic, recovery_velocity_account, recovery_velocity_device, recovery_velocity_network, recent_contact_change, completion_device_mismatch.

Velocity

The counters cover the last hour and include the current call. Each code that fires gives challenge.

• account_1h — requested stages with the same login bucket, or with the same user_id when no identifier was sent.
• device_1h — different login buckets from the same device. Business+; null on Pro.
• network_1h — different login buckets from the same /24 (IPv6: /48) network. Business+; null on Pro.

A repeat of the same login does not grow the device and network counts: they count distinct buckets. Velocity is counted on requested only; on completed the block has the same keys with null values. A visit without a device or without a network key counts as zero for that counter, not as one shared key.

Idempotency

The key is (recovery_id, stage). A repeat with the same body answers with the stored response and idempotent_replay: true, writes no second row and does not grow the velocity counters. A repeat with a different body answers 409 assessment_conflict. The body is compared by its login bucket in place of identifier, the other fields as they are.

Errors

The error body is the same envelope as everywhere in /v2.

2. hold

hold means: let some time pass before the password is written, and tell the owner. Tracio changes nothing on the account, in the sign-in or in the sessions; the delay and the notification of the old contacts are done by your app, and the time to wait comes from the response.

• hold.until is 24 hours after the first hold of the recovery_id. A second hold on the stage completed keeps the first until: repeating a stage does not extend the delay.
• The end of until sends no event: your app knows the time from the response.
• An operator of your workspace can lift a live hold in the dashboard, on the Devices & logins tab of the account card, in the Password recoveries section. The Release hold button asks for a reason and needs the workspace:general:write right. The release is written to the audit log and sent as a recovery_hold_released webhook. A hold that is already released, has no live row, is past its until or belongs to a recovery that already has an outcome cannot be released.
• GET /v2/recoveries/{recovery_id} shows hold.released_at and hold.released_by (dashboard).

3. Outcome

Report how the recovery ended. The first value wins.

curl -X POST https://api.tracio.ai/v2/recoveries/rec-8c1f/outcome \
     -H "Authorization: Bearer $TRACIO_SECRET_KEY" \
     -H "Content-Type: application/json" \
     -d '{"outcome": "executed"}'

{
  "recovery_id": "rec-8c1f",
  "outcome": "executed",
  "recorded_at": "2026-10-17T12:40:00Z",
  "trusted_devices_revoked": 2,
  "idempotent_replay": false
}

• The first call records the outcome. Any repeat — with the same or another value — answers 200 with the stored outcome and idempotent_replay: true, and changes nothing.
• 404 recovery_not_found — the workspace has no assessment with this recovery_id. 400 invalid_request — an unknown key or an outcome outside the list.
• executed revokes every live trusted device of the account in every environment of the workspace, in the same step as the record, and sets revoked_by: recovery. trusted_devices_revoked is the number of devices it revoked. Each revoke sends a trusted_device_revoked webhook.
• When no assessment of the recovery_id carried a user_id, there is no account to revoke devices of: trusted_devices_revoked is 0. A repeated executed does not revoke again. The other outcomes revoke nothing.

You do not revoke the devices yourself after a recovery if you send executed — see runbook-login-step-up.md.

4. Read a recovery

GET /v2/recoveries/{recovery_id}:

{
  "recovery_id": "rec-8c1f",
  "stages": [
    {
      "stage": "requested",
      "recommendation": "hold",
      "reasons": ["recent_contact_change"],
      "assessed_at": "2026-10-17T12:00:00Z"
    }
  ],
  "hold": {"until": "2026-10-18T12:00:00Z", "released_at": null, "released_by": null},
  "outcome": null
}

hold and outcome are null while there is none. A recovery_id of another workspace answers 404 recovery_not_found.

Webhooks

Two event types, delivered by the same webhooks as every other event — see webhooks.md for setup, signatures, retries and limits. Both are sent only on an explicit subscription by name — * does not include them — and only to webhooks on payload version 2 or 3.

allow, deny and null are not sent: deny is a bot, which is noise for an integration. The plan does not throttle the stream: Pro receives it as well. recovery_risk is not sent for an assessment whose reasons are all recovery_velocity_account, recovery_velocity_device or recovery_velocity_network (together with trusted_device, first_device and impossible_travel_anonymized); bot_traffic and any other reason send it as before. recovery_hold_released is always sent. A webhook not bound to an environment gets the events of every environment; a bound one gets its own.

The revoke of the trusted devices after executed sends trusted_device_revoked with revoked_by: "recovery" — see login-risk.md.

The events are sent by a background relay, up to about 5 seconds after the call, and carry no X-Tracio-Request-Id header. X-Tracio-Event-Id is stable: recovery-risk:<id> and recovery-hold-released:<id>; deduplicate by it. Do not wait for a webhook in the recovery flow: the decision is the synchronous answer.

recovery_risk body

The recovery_risk block is the stored assessment, in snake_case, exactly as the synchronous response gave it, without calculation_time and idempotent_replay.

{
  "version": 3,
  "event": "recovery_risk",
  "event_id": "recovery-risk:4b1f9e2c-6d3a-4f80-9b7e-2a5c8d1e0f37",
  "timestamp": "2026-10-17T12:00:00Z",
  "recovery_risk": {
    "recovery_id": "rec-8c1f",
    "stage": "requested",
    "reason": "forgot",
    "channel": "email",
    "state": "assessed",
    "not_assessed_reason": null,
    "recommendation": "hold",
    "reasons": ["recent_contact_change"],
    "hold": {"until": "2026-10-18T12:00:00Z", "released_at": null, "released_by": null},
    "device": {
      "device_ref": "7978151c54e94838",
      "new_device": false,
      "trusted": false,
      "first_seen_at": "2026-10-15T12:00:00Z",
      "last_seen_at": "2026-10-17T10:00:00Z"
    },
    "travel": null,
    "ato": null,
    "self_exclusion": null,
    "location": {"city": "Berlin", "country": "DE"},
    "velocity": {"account_1h": 1, "device_1h": null, "network_1h": null},
    "assessed_at": "2026-10-17T12:00:00Z"
  }
}

recovery_hold_released body

{
  "version": 3,
  "event": "recovery_hold_released",
  "event_id": "recovery-hold-released:4b1f9e2c-6d3a-4f80-9b7e-2a5c8d1e0f37",
  "timestamp": "2026-10-17T15:20:00Z",
  "recovery_hold_released": {
    "recovery_id": "rec-8c1f",
    "user_id": "alice",
    "hold_until": "2026-10-18T12:00:00Z",
    "released_at": "2026-10-17T15:20:00Z",
    "released_by": "dashboard"
  }
}

Plans

On Pro the Business+ codes never appear and never change the recommendation, but the journal keeps the device reference and the network key of every call: after an upgrade the counters see the earlier history. The webhook stream is not gated by the plan.

Privacy

identifier is never stored and never logged. Tracio keeps only a login bucket: 16 hex characters of an HMAC of the lower-cased login with a key of your workspace. The bucket is for counting repeats, not an identity — User@x and user@x land in the same one. The raw IP is not stored either; the journal keeps a 16-hex key of the /24 (IPv6: /48) network. The journal is kept for 90 days.

Same response with and without an account

The set of keys of the response is the same with and without user_id. The fields that depend on the account — device.new_device, device.trusted, device.first_seen_at, device.last_seen_at, travel, ato and self_exclusion — are null without one. There is no "account found" field. Your form must answer a visitor in the same way for a login that exists and one that does not.

Limits

• The login bucket is lower-case. Logins that differ only in case count as one login for velocity.
• The velocity count can miss parallel calls at the edge of the window. Two calls that run at the same moment can both see the count one short of the threshold. The counter is a recommendation, not a lock.
• The time of assess with an account and without one differs. Do not wait for assess before you answer the reset form, or the response time will tell a visitor whether the account exists. Call it after, or off the request path.
• hold blocks nothing. The 24-hour delay is yours to enforce; Tracio only tells you the time and records the release.
• review only for a link to a self-excluded account (self_excluded_link). No other reason ends with review.
• The recommendation is not a verdict on the owner. A trusted device is not proof of the owner, and a known device can be in the hands of someone else — see login-risk.md.