> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://www.openfort.io/api/mcp` to find what you need.
>
> **Have feedback?** Use `submit_feedback` on the same MCP server.

# Phone

One-time codes over SMS: send and verify codes, and phone-based password resets.

## Send OTP to phone number

`POST /iam/v2/auth/phone-number/send-otp`

Use this endpoint to send OTP to phone number

### Request body (required) (`application/json`)

- `phoneNumber` `string` _(required)_: Phone number to send OTP. Eg: "+1234567890"

### Responses

#### `200`: Success

Body (`application/json`):

- `message` `string`

#### `400`: Bad Request. Usually due to missing parameters, or invalid parameters.

Body (`application/json`):

- `message` `string` _(required)_

#### `401`: Unauthorized. Due to missing or invalid authentication.

Body (`application/json`):

- `message` `string` _(required)_

#### `403`: Forbidden. You do not have permission to access this resource or to perform this action.

Body (`application/json`):

- `message` `string`

#### `404`: Not Found. The requested resource was not found.

Body (`application/json`):

- `message` `string`

#### `429`: Too Many Requests. You have exceeded the rate limit. Try again later.

Body (`application/json`):

- `message` `string`

#### `500`: Internal Server Error. This is a problem with the server that you cannot fix.

Body (`application/json`):

- `message` `string`

### Example request

```bash
curl https://api.openfort.io/iam/v2/auth/phone-number/send-otp \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "phoneNumber": "string"
}'
```

```ts
fetch('https://api.openfort.io/iam/v2/auth/phone-number/send-otp', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    phoneNumber: 'string'
  })
})
```

## Verify phone OTP

`POST /iam/v2/auth/phone-number/verify`

Use this endpoint to verify phone number

### Request body (required) (`application/json`)

- `phoneNumber` `string` _(required)_: Phone number to verify. Eg: "+1234567890"
- `code` `string` _(required)_: OTP code. Eg: "123456"
- `disableSession` `boolean | null`: Disable session creation after verification. Eg: false
- `updatePhoneNumber` `boolean | null`: Check if there is a session and update the phone number. Eg: true

### Responses

#### `200`: Phone number verified successfully

Body (`application/json`):

- `status` `boolean` _(required)_: Indicates if the verification was successful
- `token` `string | null`: Session token if session is created, null if disableSession is true or no session is created
- `user` `object | null`: User object with phone number details, null if no user is created or found
  - `id` `string` _(required)_: Unique identifier of the user
  - `email` `string | null`: User's email address
  - `emailVerified` `boolean | null`: Whether the email is verified
  - `name` `string | null`: User's name
  - `image` `string | null`: User's profile image URL
  - `phoneNumber` `string` _(required)_: User's phone number
  - `phoneNumberVerified` `boolean` _(required)_: Whether the phone number is verified
  - `createdAt` `string <date-time>` _(required)_: Timestamp when the user was created
  - `updatedAt` `string <date-time>` _(required)_: Timestamp when the user was last updated

#### `400`: Invalid OTP

#### `401`: Unauthorized. Due to missing or invalid authentication.

Body (`application/json`):

- `message` `string` _(required)_

#### `403`: Forbidden. You do not have permission to access this resource or to perform this action.

Body (`application/json`):

- `message` `string`

#### `404`: Not Found. The requested resource was not found.

Body (`application/json`):

- `message` `string`

#### `429`: Too Many Requests. You have exceeded the rate limit. Try again later.

Body (`application/json`):

- `message` `string`

#### `500`: Internal Server Error. This is a problem with the server that you cannot fix.

Body (`application/json`):

- `message` `string`

### Example request

```bash
curl https://api.openfort.io/iam/v2/auth/phone-number/verify \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "phoneNumber": "string",
  "code": "string",
  "disableSession": true,
  "updatePhoneNumber": true
}'
```

```ts
fetch('https://api.openfort.io/iam/v2/auth/phone-number/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    phoneNumber: 'string',
    code: 'string',
    disableSession: true,
    updatePhoneNumber: true
  })
})
```

## Reset password reset with phone(forget password flow)

`POST /iam/v2/auth/phone-number/forget-password`

Request OTP for password reset via phone number

### Request body (required) (`application/json`)

- `phoneNumber` `string` _(required)_: The phone number which is associated with the user. Eg: "+1234567890"

### Responses

#### `200`: OTP sent successfully for password reset

Body (`application/json`):

- `status` `boolean` _(required)_: Indicates if the OTP was sent successfully

#### `400`: Bad Request. Usually due to missing parameters, or invalid parameters.

Body (`application/json`):

- `message` `string` _(required)_

#### `401`: Unauthorized. Due to missing or invalid authentication.

Body (`application/json`):

- `message` `string` _(required)_

#### `403`: Forbidden. You do not have permission to access this resource or to perform this action.

Body (`application/json`):

- `message` `string`

#### `404`: Not Found. The requested resource was not found.

Body (`application/json`):

- `message` `string`

#### `429`: Too Many Requests. You have exceeded the rate limit. Try again later.

Body (`application/json`):

- `message` `string`

#### `500`: Internal Server Error. This is a problem with the server that you cannot fix.

Body (`application/json`):

- `message` `string`

### Example request

```bash
curl https://api.openfort.io/iam/v2/auth/phone-number/forget-password \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "phoneNumber": "string"
}'
```

```ts
fetch('https://api.openfort.io/iam/v2/auth/phone-number/forget-password', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    phoneNumber: 'string'
  })
})
```

## Request password reset with phone

`POST /iam/v2/auth/phone-number/request-password-reset`

Request OTP for password reset via phone number

### Request body (required) (`application/json`)

- `phoneNumber` `string` _(required)_

### Responses

#### `200`: OTP sent successfully for password reset

Body (`application/json`):

- `status` `boolean` _(required)_: Indicates if the OTP was sent successfully

#### `400`: Bad Request. Usually due to missing parameters, or invalid parameters.

Body (`application/json`):

- `message` `string` _(required)_

#### `401`: Unauthorized. Due to missing or invalid authentication.

Body (`application/json`):

- `message` `string` _(required)_

#### `403`: Forbidden. You do not have permission to access this resource or to perform this action.

Body (`application/json`):

- `message` `string`

#### `404`: Not Found. The requested resource was not found.

Body (`application/json`):

- `message` `string`

#### `429`: Too Many Requests. You have exceeded the rate limit. Try again later.

Body (`application/json`):

- `message` `string`

#### `500`: Internal Server Error. This is a problem with the server that you cannot fix.

Body (`application/json`):

- `message` `string`

### Example request

```bash
curl https://api.openfort.io/iam/v2/auth/phone-number/request-password-reset \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "phoneNumber": "string"
}'
```

```ts
fetch('https://api.openfort.io/iam/v2/auth/phone-number/request-password-reset', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    phoneNumber: 'string'
  })
})
```

## Reset password with phone OTP

`POST /iam/v2/auth/phone-number/reset-password`

Reset password using phone number OTP

### Request body (required) (`application/json`)

- `otp` `string` _(required)_: The one time password to reset the password. Eg: "123456"
- `phoneNumber` `string` _(required)_: The phone number to the account which intends to reset the password for. Eg: "+1234567890"
- `newPassword` `string` _(required)_: The new password. Eg: "new-and-secure-password"

### Responses

#### `200`: Password reset successfully

Body (`application/json`):

- `status` `boolean` _(required)_: Indicates whether the password was successfully reset

#### `400`: Bad Request. Usually due to missing parameters, or invalid parameters.

Body (`application/json`):

- `message` `string` _(required)_

#### `401`: Unauthorized. Due to missing or invalid authentication.

Body (`application/json`):

- `message` `string` _(required)_

#### `403`: Forbidden. You do not have permission to access this resource or to perform this action.

Body (`application/json`):

- `message` `string`

#### `404`: Not Found. The requested resource was not found.

Body (`application/json`):

- `message` `string`

#### `429`: Too Many Requests. You have exceeded the rate limit. Try again later.

Body (`application/json`):

- `message` `string`

#### `500`: Internal Server Error. This is a problem with the server that you cannot fix.

Body (`application/json`):

- `message` `string`

### Example request

```bash
curl https://api.openfort.io/iam/v2/auth/phone-number/reset-password \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "otp": "string",
  "phoneNumber": "string",
  "newPassword": "string"
}'
```

```ts
fetch('https://api.openfort.io/iam/v2/auth/phone-number/reset-password', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    otp: 'string',
    phoneNumber: 'string',
    newPassword: 'string'
  })
})
```