# Users API Doc

## Users API

## @Authentication

## @PostNewUser

<mark style="color:green;">`POST`</mark> `http://users-api.xiot.cloud/v1/auth/signup`

Create a new user

#### Request Body

| Name                 | Type   | Description                                 |
| -------------------- | ------ | ------------------------------------------- |
| email                | string |                                             |
| firstName            | string | min:3,max:50, Arabic or English chars only. |
| lastName             | string | min:3,max50, Arabic or English chars only   |
| password             | string | min:8                                       |
| passwordConfirmation | string | Must be same as password                    |

{% tabs %}
{% tab title="200 When a user created successfully." %}

```
{
  "statusCode": 200,
  "message": "barakat.turk@gmail.com account created successfully",
  "id": "9b65fbdd-b71c-492f-b285-d95e2a83ffc6"
}
```

{% endtab %}

{% tab title="400 Validation did not pass." %}

```
{
  "statusCode": 400,
  "message": "Validation errors",
  "errors": {
    "email": "E-mail already in use"
  }
}
```

{% endtab %}
{% endtabs %}

Request Example.

```
{
	"email": "barakat.turki@gmail.com",
	"firstName": "ali",
	"lastName": "turki",
	"password": "password",
	"passwordConfirmation": "password"
}
```

## @PostLogin

<mark style="color:green;">`POST`</mark> `http://users-api.xiot.cloud/v1/auth/login`

#### Request Body

| Name     | Type   | Description |
| -------- | ------ | ----------- |
| email    | string |             |
| password | string |             |

{% tabs %}
{% tab title="200 Send the access token with every user's request." %}

```
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVkYjRmOWI2LTgyNTMtNDQ3Zi05NzEzLWRjNzQyZGFhMjIxNCIsImlhdCI6MTU3ODM4MzE5MiwiZXhwIjoxNTc4NDY5NTkyLCJpc3MiOiJodHRwczovL3hpb3QuaW8ifQ.2AzZjspVSmcGoFHYcGPP9U0ty5PCCm1xadLrEAeBqnU",
  "user": {
    "id": "5db4f9b6-8253-447f-9713-dc742daa2214",
    "firstName": "ali",
    "lastName": "turki",
    "email": "barakat.turki@gmail.com",
    "emailVerified": true,
    "phoneVerified": false
  }
}
```

{% endtab %}

{% tab title="201 Send the loginCode  with the code\@VerifyTOTP API" %}

```
{
  "statusCode": 201,
  "message": "user has two factor authentication",
  "loginCode": "6e41febee0e90fb7"
}
```

{% endtab %}

{% tab title="400 " %}

```
{
  "statusCode": 400,
  "message": "Validation errors",
  "errors": {
    "password": "the field is required"
  }
}
```

{% endtab %}

{% tab title="401 " %}

```
{
  "statusCode": 401,
  "message": "Invalid email or password."
}
```

{% endtab %}

{% tab title="422 when a user is already signed up and has not activated his email." %}

```
{
  "statusCode": 422,
  "message": "User's email is not verified, and verification email has just sent again."
}
```

{% endtab %}
{% endtabs %}

## @VerifyTOTP&#x20;

<mark style="color:green;">`POST`</mark> `http://users-api.xiot.cloud/v1/auth/verify-totp`

**Only if the two factor authenticated is enabled**

#### Request Body

| Name      | Type   | Description                                                            |
| --------- | ------ | ---------------------------------------------------------------------- |
| loginCode | string | code sent back from login api                                          |
| code      | string | code comes form two factor authentication APP ex: google authenticator |

{% tabs %}
{% tab title="200 " %}

```
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjFhNTk0YzI1LTliZGMtNGFlYy05NWJiLTY2ZTY5YzkyOWM3MCIsImlhdCI6MTU3OTc4NTg0MywiZXhwIjoxNTc5ODcyMjQzLCJpc3MiOiJodHRwczovL3hpb3QuaW8ifQ.LDvB5uo0qnBlwY27KZ5otJxdWSI_0QSJ5msrxA0gBss",
  "user": {
    "id": "1a594c25-9bdc-4aec-95bb-66e69c929c70",
    "firstName": "ali",
    "lastName": "turki",
    "email": "barakat.turki@gmail.com",
    "emailVerified": true,
    "phoneVerified": false
  }
}
```

{% endtab %}

{% tab title="400 " %}

```
{
  "statusCode": 400,
  "message": "loginCode expired or invalid",
  "field": "loginCode",
  "moreErrors": {}
}
```

{% endtab %}
{% endtabs %}

## @Profile

## @GetUserProfile

<mark style="color:blue;">`GET`</mark> `http://users-api.xiot.cloud/v1/profile`

#### Headers

| Name          | Type   | Description              |
| ------------- | ------ | ------------------------ |
| authorization | string | send bearer access token |

{% tabs %}
{% tab title="200 " %}

```
{
  "statusCode": 200,
  "message": "User's data",
  "data": {
    "id": "5db4f9b6-8253-447f-9713-dc742daa2214",
    "uid": "7b16b343-3c38-4ede-860a-ffc6b081a802",
    "firstName": "ali",
    "lastName": "turki",
    "email": "barakat.turki@gmail.com",
    "phone": null,
    "emailVerified": true,
    "phoneVerified": false,
    "providerId": null,
    "createdAt": "2020-01-01T13:56:43.962Z",
    "updatedAt": "2020-01-04T15:31:10.707Z"
  }
}
```

{% endtab %}

{% tab title="401 Invalid access token or it's not sent." %}

```
Unauthorized
```

{% endtab %}
{% endtabs %}

## @UpdateProfile

<mark style="color:orange;">`PUT`</mark> `http://users-api.xiot.cloud/v1/profile`

#### Headers

| Name          | Type   | Description |
| ------------- | ------ | ----------- |
| authorization | string |             |

#### Request Body

| Name      | Type   | Description                                    |
| --------- | ------ | ---------------------------------------------- |
| phone     | string | valid egp phone number                         |
| lastName  | string | min:3,max:50,valid english and arabic  letters |
| firstName | string | min:3,max:50,vaild english and arabic letters  |

{% tabs %}
{% tab title="200 " %}

```
{
  "statusCode": 200,
  "message": "profile update successfully"
}
```

{% endtab %}

{% tab title="400 " %}

```
{
  "statusCode": 400,
  "message": "Validation errors",
  "errors": {
    "phone": "Invalid value",
    "firstName": "the field is required",
    "lastName": "the field is required"
  }
}
```

{% endtab %}
{% endtabs %}

## @Security

## @ChangePassword

<mark style="color:orange;">`PUT`</mark> `http://users-api.xiot.cloud/v1/security/change-password`

Change logged in user's password

#### Headers

| Name          | Type   | Description  |
| ------------- | ------ | ------------ |
| authorization | string | Bearer Token |

#### Request Body

| Name                 | Type   | Description |
| -------------------- | ------ | ----------- |
| oldPassword          | string |             |
| password             | string |             |
| passwordConfirmation | string |             |

{% tabs %}
{% tab title="200 " %}

```
{
  "statusCode": 200,
  "message": "user's password changed successfully."
}
```

{% endtab %}

{% tab title="400 " %}

```
{
  "statusCode": 400,
  "message": "must be at least 8 chars long",
  "field": "password",
  "moreErrors": {
    "passwordConfirmation": "Must have the same value as the password field"
  }
}
```

{% endtab %}
{% endtabs %}

## @ForgetPassword

<mark style="color:green;">`POST`</mark> `http://users-api.xiot.cloud/v1/security/forget-password`

#### Request Body

| Name  | Type   | Description                            |
| ----- | ------ | -------------------------------------- |
| email | string | Valid Email Format - Required - Exists |

{% tabs %}
{% tab title="200 " %}

```
{
  "statusCode": 200,
  "message": "reset token sent to user's email"
}
```

{% endtab %}

{% tab title="400 " %}

```
{
  "statusCode": 400,
  "message": "Invalid E-mail format",
  "field": "email",
  "moreErrors": {}
}
```

{% endtab %}
{% endtabs %}

## @EnableTwoFactorAuth

<mark style="color:green;">`POST`</mark> `http://users-api.xiot.cloud/v1/security/twofactor-enable`

#### Headers

| Name          | Type   | Description  |
| ------------- | ------ | ------------ |
| authorization | string | Bearer Token |

{% tabs %}
{% tab title="200 " %}
{% code title="QRCODE IMAGE" %}

```
```

{% endcode %}
{% endtab %}
{% endtabs %}

## @DisableTwoFactorAuth

<mark style="color:green;">`POST`</mark> `http://users-api.xiot.cloud/v1/security/twofactor-disable`

#### Headers

| Name          | Type   | Description  |
| ------------- | ------ | ------------ |
| authorization | string | Bearer Token |

{% tabs %}
{% tab title="200 " %}

```
{
  "statusCode": 200,
  "message": "Two factor authentication disabled"
}
```

{% endtab %}
{% endtabs %}

## @Account

## @ChangeEmail

<mark style="color:orange;">`PUT`</mark> `http://users-api.xiot.cloud/v1/account/change-email`

#### Headers

| Name          | Type   | Description  |
| ------------- | ------ | ------------ |
| authorization | string | Bearer Token |

#### Request Body

| Name  | Type   | Description                 |
| ----- | ------ | --------------------------- |
| email | string | Unique - valid email format |

{% tabs %}
{% tab title="200 " %}

```
{
  "statusCode": 200,
  "message": "Email changed successfully and we sent a verification code to your email."
}
```

{% endtab %}

{% tab title="400 " %}

```
{
  "statusCode": 400,
  "message": "Invalid E-mail format",
  "field": "email",
  "moreErrors": {}
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://api-docs.xiot.cloud/master.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.