<!-- llms.txt: https://workos.com/llms.txt -->

# Password reset

Create a password reset token for a user and reset the user's password.

> When a user's password is reset, all of their active sessions are revoked.

## Create a password reset token

Creates a one-time token that can be used to reset a user's password.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request POST \
  --url "https://api.workos.com/user_management/password_reset" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "email": "marcelina.davis@example.com"
    }
BODY
```

```js language="js" title="Request" tab="1"
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const passwordReset = await workos.userManagement.createPasswordReset({
  email: 'marcelina@example.com',
});
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.user_management.reset_password(email: "marcelina.davis@example.com")
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.user_management.reset_password(email="marcelina.davis@example.com")
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.UserManagement().ResetPassword(context.Background(), &workos.UserManagementResetPasswordParams{
		Email: "marcelina.davis@example.com",
	})
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos->userManagement()->resetPassword(email: "marcelina.davis@example.com");
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;
import com.workos.usermanagement.UserManagementApi.ResetPasswordOptions;

WorkOS workos = new WorkOS("sk_example_123456789");

ResetPasswordOptions options =
    ResetPasswordOptions.builder().email("marcelina.davis@example.com").build();

workos.userManagement.resetPassword(options);
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.UserManagement.ResetPasswordAsync(new UserManagementResetPasswordOptions {
    Email = "marcelina.davis@example.com",
});
```

```rust language="rust" title="Request" tab="1"
use workos::Client;
use workos::user_management::ResetPasswordParams;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .user_management()
        .reset_password(
            ResetPasswordParams {
                email: "marcelina.davis@example.com".into(),
                ..Default::default()
            }
        )
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "password_reset",
  "id": "password_reset_01E4ZCR3C56J083X43JQXF3JK5",
  "user_id": "user_01E4ZCR3C56J083X43JQXF3JK5",
  "email": "marcelina.davis@example.com",
  "expires_at": "2026-01-15T12:00:00.000Z",
  "created_at": "2026-01-15T12:00:00.000Z",
  "password_reset_token": "Z1uX3RbwcIl5fIGJJJCXXisdI",
  "password_reset_url": "https://your-app.com/reset-password?token=Z1uX3RbwcIl5fIGJJJCXXisdI"
}
```

:::

## Get a password reset token

Get the details of an existing password reset token that can be used to reset a user's password.

:::code-group

```bash language="curl" title="Request" tab="1"
curl "https://api.workos.com/user_management/password_reset/password_reset_01E4ZCR3C56J083X43JQXF3JK5" \
  --header "Authorization: Bearer sk_example_123456789"
```

```js language="js" title="Request" tab="1"
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const passwordReset = await workos.userManagement.getPasswordReset(
  'password_reset_01HYGDNK5G7FZ4YJFXYXPB5JRW',
);
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.user_management.get_password_reset(id: "password_reset_01E4ZCR3C56J083X43JQXF3JK5")
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.user_management.get_password_reset(
    id_="password_reset_01E4ZCR3C56J083X43JQXF3JK5"
)
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.UserManagement().GetPasswordReset(context.Background(), "password_reset_01E4ZCR3C56J083X43JQXF3JK5")
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->userManagement()
    ->getPasswordReset(id: "password_reset_01E4ZCR3C56J083X43JQXF3JK5");
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.userManagement.getPasswordReset("password_reset_01E4ZCR3C56J083X43JQXF3JK5");
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.UserManagement.GetPasswordResetAsync("password_reset_01E4ZCR3C56J083X43JQXF3JK5");
```

```rust language="rust" title="Request" tab="1"
use workos::Client;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .user_management()
        .get_password_reset("password_reset_01E4ZCR3C56J083X43JQXF3JK5")
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "password_reset",
  "id": "password_reset_01E4ZCR3C56J083X43JQXF3JK5",
  "user_id": "user_01E4ZCR3C56J083X43JQXF3JK5",
  "email": "marcelina.davis@example.com",
  "expires_at": "2026-01-15T12:00:00.000Z",
  "created_at": "2026-01-15T12:00:00.000Z",
  "password_reset_token": "Z1uX3RbwcIl5fIGJJJCXXisdI",
  "password_reset_url": "https://your-app.com/reset-password?token=Z1uX3RbwcIl5fIGJJJCXXisdI"
}
```

:::

## Reset the password

Sets a new password using the `token` query parameter from the link that the user received. Successfully resetting the password will verify a user's email, if it hasn't been verified yet.

:::code-group{title="Request"}

```bash language="curl"
curl --request POST \
  --url https://api.workos.com/user_management/password_reset/confirm \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<BODY
  {
    "token": "stpIJ48IFJt0HhSIqjf8eppe0",
    "new_password": "i8uv6g34kd490s"
  }
BODY
```

```js language="js"
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const { user } = await workos.userManagement.resetPassword({
  token: 'stpIJ48IFJt0HhSIqjf8eppe0',
  newPassword: 'i8uv6g34kd490s',
});
```

```rb language="ruby"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.user_management.confirm_password_reset(
  token: "Z1Y2X3W4V5U6T7S8R9Q0P1O2N3",
  new_password: "strong_password_123!"
)
```

```py language="python"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.user_management.confirm_password_reset(
    token="Z1Y2X3W4V5U6T7S8R9Q0P1O2N3", new_password="strong_password_123!"
)
```

```go language="go"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.UserManagement().ConfirmPasswordReset(context.Background(), &workos.UserManagementConfirmPasswordResetParams{
		Token:       "Z1Y2X3W4V5U6T7S8R9Q0P1O2N3",
		NewPassword: "strong_password_123!",
	})
	if err != nil {
		panic(err)
	}
}
```

```php language="php"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->userManagement()
    ->confirmPasswordReset(
        token: "Z1Y2X3W4V5U6T7S8R9Q0P1O2N3",
        newPassword: "strong_password_123!",
    );
```

```java language="java"
import com.workos.WorkOS;
import com.workos.usermanagement.UserManagementApi.ConfirmPasswordResetOptions;

WorkOS workos = new WorkOS("sk_example_123456789");

ConfirmPasswordResetOptions options = ConfirmPasswordResetOptions.builder()
                                          .token("Z1Y2X3W4V5U6T7S8R9Q0P1O2N3")
                                          .newPassword("strong_password_123!")
                                          .build();

workos.userManagement.confirmPasswordReset(options);
```

```cs language="dotnet"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.UserManagement.ConfirmPasswordResetAsync(new UserManagementConfirmPasswordResetOptions {
    Token = "Z1Y2X3W4V5U6T7S8R9Q0P1O2N3",
    NewPassword = "strong_password_123!",
});
```

```rust language="rust"
use workos::Client;
use workos::user_management::ConfirmPasswordResetParams;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .user_management()
        .confirm_password_reset(
            ConfirmPasswordResetParams {
                token: "Z1Y2X3W4V5U6T7S8R9Q0P1O2N3".into(),
                new_password: "strong_password_123!".into(),
                ..Default::default()
            }
        )
        .await?;

    Ok(())
}
```

:::

### password_reset

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The unique ID of the password reset object. |
| `user_id` | string | Yes | The unique ID of the user. |
| `email` | string | Yes | The email address of the user. |
| `password_reset_token` | string | Yes | The token used to reset the password. |
| `password_reset_url` | string | Yes | The URL where the user can reset their password. |
| `expires_at` | string | Yes | The timestamp when the password reset token expires. |
| `created_at` | string | Yes | The timestamp when the password reset token was created. |

### POST /user_management/password_reset

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string | Yes | The email address of the user requesting a password reset. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `password_reset` | object | Distinguishes the password reset object. |

### GET /user_management/password_reset/{id}

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The ID of the password reset token. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `password_reset` | object | Distinguishes the password reset object. |

### POST /user_management/password_reset/confirm

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | string | Yes | The `token` query parameter from the password reset URL. |
| `new_password` | string | Yes | The new password to set for the user. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `user` | object | The user whose password was reset. |