> For the complete documentation index, see [llms.txt](https://switchng.gitbook.io/switch/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://switchng.gitbook.io/switch/master.md).

# Authentication

```
STAGING_URL: https://switchapi3.azurewebsites.net
LIVE_URL: https://switchapi.azurewebsites.net
```

## Register User

<mark style="color:green;">`POST`</mark> `https://switchapi3.azurewebsites.net/user/register`

Registers user and returns a valid token used for session validation

#### Headers

| Name    | Type   | Description      |
| ------- | ------ | ---------------- |
| SWI-CS  | string | Payload checksum |
| SWI-CID | string | Client ID        |

#### Request Body

| Name                         | Type   | Description                                                                                                                                        |
| ---------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| sales\_agent\_referral\_code | string | Referral code of the sales agent.                                                                                                                  |
| referrer                     | string | Switch ID of the referrer.                                                                                                                         |
| bvn                          | string | The user's bvn. Required for Nigerian users.                                                                                                       |
| country                      | string | country of user, default is \`nigeria\`                                                                                                            |
| gender                       | string | gender of user                                                                                                                                     |
| date\_of\_birth              | string | date of birth of user, in the format YYYY-MM-DD                                                                                                    |
| phone                        | number | preferred phone number of user                                                                                                                     |
| last\_name                   | string | last name of user                                                                                                                                  |
| first\_name                  | string | first name of user                                                                                                                                 |
| password                     | string | preferred password of user, which must contain at least one upper case letter, one lower case letter, one digit and at least one special character |
| email                        | string | email address of user                                                                                                                              |

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

```
{
  "message": "User created successfully",
  "data": {
    "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoiMzk2IiwiY29udGV4dCI6InVzZXIiLCJpYXQiOjE1NzcyODg1MjksImV4cCI6MTU3NzI5MDMyOX0.2AwxVSj2QzYCB5cZySUjJ8nRU3guZHtgQbvl1BcQWyc",
    "user": {
      "is_verified": false,
      "blacklisted": false,
      "two_factor_authentication_enabled": false,
      "two_factor_authentication_type": "none",
      "phone_verified": false,
      "pin_set": false,
      "google_auth_set_up": false,
      "disabled": false,
      "has_pending_disable_request": false,
      "has_pending_enable_request": false,
      "fraud_status": "whitelisted",
      "id": "396",
      "email": "someone@gmail.com",
      "first_name": "Somebody",
      "last_name": "Anybody",
      "date_of_birth": "1996-10-06",
      "phone": "+2348097635343",
      "gender": "male",
      "country": "NG",
      "photo_id_url": null,
      "image_selfie_url": null,
      "signature_url": null,
      "address": null,
      "switch_id": 100496,
      "payment_link_slug": null,
      "city": null,
      "state": null,
      "zipcode": null,
      "last_sign_in": null,
      "photo_id_issuer": null,
      "photo_id_number": null,
      "photo_id_expiry": null,
      "switch_bank_account_name": null,
      "switch_bank_account_number": null,
      "nigerian_contact_name": null,
      "nigerian_contact_phone": null,
      "nigerian_contact_address": null,
      "nigerian_contact_relationship": null,
      "switch_bank_customer_id": null,
      "verified_at": null,
      "verification_requested": false,
      "bvn": "22xxxxxx032",
      "security_question_set": false,
      "is_diaspora": false,
      "has_wallet": false
    }
  }
}
```

{% endtab %}

{% tab title="400 " %}

```
{
  "message": "Error occurred creating user",
  "errors": {
    "password": "must contain at least one upper case letter, one lower case letter, one digit and at least one special character"
  }
}
```

{% endtab %}
{% endtabs %}

## Login User

<mark style="color:green;">`POST`</mark> `https://switchapi3.azurewebsites.net/user/login`

Authenticates user and returns a valid token used for session validation.

#### Headers

| Name    | Type   | Description      |
| ------- | ------ | ---------------- |
| SWI-CS  | string | Payload checksum |
| SWI-CID | string | Client ID        |

#### Request Body

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

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

```javascript
{
  "message": "User login successful",
  "data": {
    "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoiMTEiLCJjb250ZXh0IjoidXNlciIsImlhdCI6MTU3NzI4ODkwMCwiZXhwIjoxNTc3MjkwNzAwfQ.Aqt4XZbsQqc8UqEuh51ytc7IrNMEhXSPFSvdX3BQSpw",
    "user": {
      "id": "11",
      "email": "beyonceknowles@gmail.com",
      "phone": "+2348154634619",
      "first_name": "Beyonce",
      "last_name": "Knowles",
      "date_of_birth": "1981-09-04",
      "photo_id_url": "+2348154634619_id_card_beyonce.jpg",
      "image_selfie_url": "+2348154634619_image_selfie_url_beyonce.jpg",
      "signature_url": null,
      "address": "19, Okotie Eboh",
      "is_verified": false,
      "gender": "female",
      "country": "NG",
      "blacklisted": false,
      "switch_id": 100111,
      "two_factor_authentication_enabled": true,
      "two_factor_authentication_type": "pin",
      "phone_verified": true,
      "pin_set": true,
      "payment_link_slug": "100111",
      "city": "Ikoyi",
      "state": "Lagos",
      "zipcode": "101233",
      "last_sign_in": "2019-02-11T13:21:59.409Z",
      "photo_id_issuer": null,
      "photo_id_number": null,
      "photo_id_expiry": null,
      "switch_bank_account_name": null,
      "switch_bank_account_number": null,
      "google_auth_set_up": false,
      "nigerian_contact_name": null,
      "nigerian_contact_phone": null,
      "nigerian_contact_address": null,
      "nigerian_contact_relationship": null,
      "switch_bank_customer_id": null,
      "disabled": false,
      "has_pending_disable_request": false,
      "has_pending_enable_request": false,
      "fraud_status": "whitelisted",
      "verified_at": null,
      "verification_requested": false,
      "bvn": null,
      "security_question_set": true,
      "is_diaspora": false,
      "has_wallet": true
    }
  }
}
```

{% endtab %}

{% tab title="401 Unsuccessful login" %}

```javascript
{
    "message": "Invalid login details"
}
```

{% endtab %}
{% endtabs %}

## Forgot Password

<mark style="color:green;">`POST`</mark> `https://switchapi3.azurewebsites.net/user/forgot_password`

Creates a reset password token, attaches it to user account and sends a reset link to user's email

#### Headers

| Name    | Type   | Description      |
| ------- | ------ | ---------------- |
| SWI-CS  | string | Payload checksum |
| SWI-CID | string | Client ID        |

#### Request Body

| Name  | Type   | Description           |
| ----- | ------ | --------------------- |
| email | string | email address of user |

{% tabs %}
{% tab title="200 password reset email  successfully sent" %}

```
{
    "message": "If this email exists, a password reset email will be sent to it"
}
```

{% endtab %}
{% endtabs %}

## Reset Password

<mark style="color:green;">`POST`</mark> `https://switchapi3.azurewebsites.net/user/reset_password`

Resets user password

#### Headers

| Name    | Type   | Description      |
| ------- | ------ | ---------------- |
| SWI-CS  | string | Payload checksum |
| SWI-CID | string | Client ID        |

#### Request Body

| Name                       | Type    | Description                                                                                            |
| -------------------------- | ------- | ------------------------------------------------------------------------------------------------------ |
| security\_question\_answer | string  | The answer to the security question. Required only if the user has set one or more security questions. |
| security\_question\_id     | integer | The id of the security question. Required only if the user has set one or more security questions      |
| password\_confirmation     | object  | password confirmation                                                                                  |
| reset\_password\_token     | string  | the token that was sent to the user via email                                                          |
| password                   | string  | the preferred password                                                                                 |

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

```
{
    "message": "Password changed successfully"
}
```

{% endtab %}

{% tab title="400 " %}

```
{
    "message": "Password could not be updated",
    "errors": {
        "password": "can't be blank"
    }
}
```

{% endtab %}
{% endtabs %}

## Unlock Account

<mark style="color:green;">`POST`</mark> `https://switchapi3.azurewebsites.net/user/unlock_account`

Unlocks a locked account

#### Headers

| Name    | Type   | Description      |
| ------- | ------ | ---------------- |
| SWI-CS  | string | Payload checksum |
| SWI-CID | string | Client ID        |

#### Request Body

| Name          | Type   | Description                                 |
| ------------- | ------ | ------------------------------------------- |
| unlock\_token | string | the unlock token sent to the user via email |

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

```
{
    "message": "Account unlocked successfully"
}
```

{% endtab %}

{% tab title="400 " %}

```
{
    "message": "Account could not be unlocked",
    "errors": {
        "unlock_token": "is invalid"
    }
}
```

{% endtab %}
{% endtabs %}

## Resend Unlock Email

<mark style="color:green;">`POST`</mark> `https://switchapi3.azurewebsites.net/user/resend_unlock_email`

Re-sends the unlock email

#### Headers

| Name    | Type   | Description      |
| ------- | ------ | ---------------- |
| SWI-CS  | string | Payload checksum |
| SWI-CID | string | Client ID        |

#### Request Body

| Name  | Type   | Description |
| ----- | ------ | ----------- |
| email | string | user email  |

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

```
{
    "message": "If this email exists and there's a lock, unlock instructions will be sent to it"
}
```

{% endtab %}
{% endtabs %}

## Logout

<mark style="color:green;">`POST`</mark> `https://switchapi3.azurewebsites.net/user/logout`

Invalidates the session token

#### Headers

| Name          | Type   | Description                                    |
| ------------- | ------ | ---------------------------------------------- |
| SWI-CS        | string | Payload checksum                               |
| SWI-CID       | string | Client ID                                      |
| Authorization | string | token in the format ***Bearer token\_string*** |

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

```
{
    "message": "User session invalidated"
}
```

{% endtab %}

{% tab title="401 " %}

```
{
    "message": "Invalid token"
}
```

{% endtab %}
{% endtabs %}

## Validate user's BVN details

<mark style="color:green;">`POST`</mark> `https://switchapi3.azurewebsites.net/user/validate_user_bvn`

Validates the user's bvn.

#### Headers

| Name    | Type   | Description      |
| ------- | ------ | ---------------- |
| SWI-CS  | string | Payload checksum |
| SWI-CID | string | Client ID        |

#### Request Body

| Name            | Type   | Description               |
| --------------- | ------ | ------------------------- |
| date\_of\_birth | string | The user's date of birth. |
| last\_name      | string | The user's last name.     |
| first\_name     | string | The user's first name.    |
| bvn             | string | The user's bvn.           |

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

```
{
    "message": "BVN validated successfully"
}
```

{% endtab %}

{% tab title="400 " %}

```
{
    "message": "BVN is invalid, please confirm your bvn and try again"
}
```

{% endtab %}
{% endtabs %}

## Send email confirmation

<mark style="color:green;">`POST`</mark> `https://switchapi3.azurewebsites.net/user/send_email_confirmation_mail`

This endpoint is used to send a confirmation email to a user.

#### Headers

| Name    | Type   | Description      |
| ------- | ------ | ---------------- |
| SWI-CS  | string | Payload checksum |
| SWI-CID | string | Client ID        |

#### Request Body

| Name  | Type   | Description      |
| ----- | ------ | ---------------- |
| email | string | The user's email |

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

```
{
  "message": "Confirmation email sent"
}
```

{% endtab %}
{% endtabs %}

## Get Referrer

<mark style="color:blue;">`GET`</mark> `https://switchapi3.azurewebsites.net/user/referrer/:switch_id`

This endpoint gets the referrer using the switch\_id.

#### Path Parameters

| Name       | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| switch\_id | string | The switch\_id of the referrer. |

#### Headers

| Name    | Type   | Description |
| ------- | ------ | ----------- |
| SWI-CID | string | Client ID   |

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

```
{
    "message": "Referrer retrieved successfully",
    "data": {
        "first_name": "Dan",
        "last_name": "Sawyerr",
        "switch_id": "100789"
    }
}
```

{% endtab %}

{% tab title="400 " %}

```
{
    "message": "Invalid referral link"
}
```

{% endtab %}
{% endtabs %}