Wocha Docs

User recovery API

POST /v1/users/{id}/recovery — send or return a set-password link for an existing identity

Create a password recovery / set-password link for an existing user. This is not the organisation invite API. Invites that should create membership and a first-password experience must use Organisation invites.

MethodPOST
Path/v1/users/{id}/recovery
Scopeusers:write
Success200 OK

Request

POST /v1/users/{id}/recovery
Authorization: Bearer wocha_mgmt_...
Content-Type: application/json
{
  "return_to": "https://app.example.com/api/auth/login",
  "send": false
}
FieldTypeDefaultDescription
return_tohttps URI—Allowlisted URL after the user sets a password
sendbooleantrueWhen false, do not email; return recovery_link
emailboolean—Legacy alias of send. email: false is treated as send: false

An empty body is valid and emails the recovery template.

Response

Wocha sends mail (send true)

{
  "emailed": true,
  "expires_at": "2026-08-22T12:00:00.000Z",
  "provider": "resend",
  "return_to": "https://app.example.com/api/auth/login"
}
{
  "emailed": false,
  "recovery_link": "https://id.wocha.ai/recovery?flow=…&token=…&return_to=…&org_id=…",
  "expires_at": "2026-08-22T12:00:00.000Z",
  "return_to": "https://app.example.com/api/auth/login"
}

The hosted URL is rewritten onto id.wocha.ai/recovery so the session cookie lands on the Auth origin. Query params include return_to (when allowlisted) and org_id when the identity has an org hint. Completing the token persists those values in cookies before Kratos finishes the flow.

SDKs

await wocha.users.sendRecovery(userId, {
  return_to: "https://app.example.com/api/auth/login",
  send: false,
});
client.users.send_recovery(
    user_id,
    return_to="https://app.example.com/api/auth/login",
    send=False,
)
Loading playground…

Errors

StatusCodeWhen
400validation_errorIdentity has no email, or return_to is not allowlisted
404not_foundUser not found in this tenant
502upstream_errorIdentity service failed to create the link
503service_unavailableIdentity service is not configured

See also

Previous

SMS MFA API

Next

API reference

On this page