# passwords.reset

Reset a mailbox password as an administrator.

Sets a new password on every password credential the mailbox has, creating one if it has none (named after the primary address, or the group address for a group persona), and revokes every expiring credential (browser sessions) so nothing minted before the reset survives it. App passwords are kept unless revokeAppPasswords is set. The mailbox is notified. Callable with an account key or a system key; a mailbox's own bearer uses PUT /password instead, which proves the current password.

```ts
openemail.passwords.reset(
  identityId: string,
  body: PasswordsResetBody,
  options?: CallOptions,
): ApiPromise<RecoveryCompleted>
```

It calls `POST /identities/{identityId}/password/reset`: [Reset a mailbox password as an administrator](/docs/api/credentials/post_MailboxPasswordReset) in the API reference.

## Example

```ts
const recoveryCompleted = await openemail.passwords.reset(identityId, { newPassword: '…' })
```

## Arguments

| Argument | Type | Description |
| --- | --- | --- |
| `identityId` | `string` | Mailbox identity ULID. The path's `{identityId}`. |
| `body` | [`PasswordsResetBody`](#passwordsresetbody) | The request's body. |

## Options

It takes no options of its own. Every call also takes `signal`, `timeout`, `retry` and `headers`, which say how that one call is sent ([call options](/docs/sdks/typescript/calling-methods#call-options)).

## Answer

Awaited, it is the API's JSON, [`RecoveryCompleted`](/docs/sdks/typescript/types/recovery-completed). It is an [`ApiPromise`](/docs/sdks/typescript/responses): `.withResponse()` gives the same with the `Response` it came in, for its headers.

## Errors

| Status | What it means |
| --- | --- |
| `400` | validation_failed |
| `401` | unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge |
| `404` | Mailbox not found or not accessible to this principal |
| `409` | no_username — the identity has no password credential to rotate and no address (primary or group) to name a new one after; nothing was changed. Create the login with POST /credentials and an explicit username |
| `413` | too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing |
| `503` | temporary_failure (with Retry-After): under the object directory, the account's identity census could not be updated just now, so the write that would move it was not made; retry the same request after the Retry-After window |

A failed call rejects with a [`RequestError`](/docs/sdks/typescript/errors): its `status`, and its `code`, the API's `error`. Decide on the code: one status covers several.

## Types

### PasswordsResetBody

```ts
/** The body of `passwords.reset`. */
type PasswordsResetBody = {
  /** The password to set */
  newPassword: string
  /** Revoke the mailbox's non-expiring app passwords too. Off by default, on when the reset is a response to a compromise rather than to a forgotten password */
  revokeAppPasswords?: boolean
}
```

It names these types of the API, each on a page of its own: [`RecoveryCompleted`](/docs/sdks/typescript/types/recovery-completed).
