# Send a password reset email

`POST /v1/users/{user_id}:send-password-reset` · permission `user-credentials:write`

Sends the password reset link (valid for 24 hours) to the user's primary email. The address is not part of the request and the link is never returned. The optional body only selects the email language. Send an `Idempotency-Key` header to make retries safe.

## Request

| Parameter | In | Required | Description |
|---|---|---|---|
| `user_id` | path | yes | User id, prefixed `usr_`. |

Optional body:

| Field | Type | Required | Description |
|---|---|---|---|
| `locale` | string | no | BCP 47 language tag of the email, for example `tr` or `pt-BR`. Defaults to the user's or the environment's language. |

## Response

`204 No Content`. The body is empty; the link is not returned.

## Errors

Every error is an `application/problem+json` body with a stable `code`.

| HTTP | `code` | When |
|---|---|---|
| 400 | `malformed_request`, `unknown_field` | The body is not valid JSON or has an unknown field. |
| 409 | `conflict` | The user has no primary email, or it is not verified. |
| 415 | `unsupported_media_type` | A body was sent without `Content-Type: application/json`. |
| 422 | `validation_failed` | `locale` is not a valid BCP 47 language tag, or a field has the wrong type. |
| 404 | `not_found` | The user does not exist in this environment (or the id is malformed). |
| 401 | `unauthenticated` | The API key is missing, invalid or revoked. |
| 403 | `insufficient_permissions` | The key lacks the `user-credentials:write` permission. |
| 429 | `rate_limited` | The API rate limit or the per-user email sending limit was exceeded; honor `Retry-After`. |
| 503 | `service_unavailable` | A dependency is temporarily unavailable; retry later. |

## Example

```bash
curl -X POST https://api.eu.keenauth.com/v1/users/usr_0a1b2c3d4e5f6g7h8j9k0m1n2p:send-password-reset \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"locale": "en"}'
```