> For the complete documentation index, see [llms.txt](https://eyowo.gitbook.io/eyowo-developer-apis/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://eyowo.gitbook.io/eyowo-developer-apis/staging/api-resources/authentication.md).

# Authentication

Authenticating a user's account and retrieving a wallet access token grants you, the developer, privileges to perform certain transactions like Phone Transfers, Bank Transfer, and purchasing VTU(s).

To obtain a wallet access token (`X-App-Wallet-Access-Token`), you have to validate the account is a valid Eyowo account, send an OTP, and finally, verify the OTP.

## Validate User

<mark style="color:green;">`POST`</mark> `https://api.console.staging-api.eyowo.com/v1/users/auth/validate`

`Usage: { "mobile" : "2348000000" }`

#### Headers

| Name      | Type   | Description |
| --------- | ------ | ----------- |
| X-App-Key | string | `X-App-Key` |

#### Request Body

| Name   | Type   | Description                         |
| ------ | ------ | ----------------------------------- |
| mobile | string | `2348012345678 <valid Nigeria num>` |

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

```
{
  "success": true,
  "data": {
    "user": {
      "id": "OKHN8E4SS",
      "mobile": "2348000000000"
    }
  },
  "message": "Validation successful"
}
```

{% endtab %}

{% tab title="404 User does not exist" %}

```
{
    "success": false,
    "error": "This user does not exist",
    "errorCode": "10003"
}
```

{% endtab %}
{% endtabs %}

## Send OTP&#x20;

<mark style="color:green;">`POST`</mark> `https://api.console.staging-api.eyowo.com/v1/users/auth`

`Usage: { "mobile" : "23480000000000" , "factor" : "sms" }`&#x20;

#### Headers

| Name      | Type   | Description |
| --------- | ------ | ----------- |
| X-App-Key | string | `X-App-Key` |

#### Request Body

| Name   | Type   | Description                          |
| ------ | ------ | ------------------------------------ |
| mobile | string | `2348012345678 <valid Nigerian num>` |
| factor | string | `sms`                                |

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

```
{
  "success": true,
  "message": "Please enter the passcode sent to 2348000000000"
}
```

{% endtab %}
{% endtabs %}

## Verify OTP

<mark style="color:green;">`POST`</mark> `https://api.console.staging-api.eyowo.com/v1/users/auth`

`Usage: { "mobile" : "234809999999", "factor": "sms", "passcode": "1234" }`

#### Headers

| Name      | Type   | Description |
| --------- | ------ | ----------- |
| X-App-Key | string | `X-App-Key` |

#### Request Body

| Name     | Type   | Description                           |
| -------- | ------ | ------------------------------------- |
| mobile   | string | `23480123456789 <valid Nigerian num>` |
| factor   | string | `sms`                                 |
| passcode | string | `12345 <valid otp>`                   |

{% tabs %}
{% tab title="200 Wallet access token generated successful" %}

```
{
    "success": true,
    "message": "Wallet added successfully",
    "data": {
        "refreshToken": "5d07619d019bd118ae99786f3a34840d999b1e84",
        "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVkMDc2MTlkMDE5YmQxMThhZTk5Nzg2ZiIsIm1vYmlsZSI6IjIzNDgxODQyMDkxODgiLCJpYXQiOjE1NjA3NjQ4MjksImV4cCI6MTU2MDg1MTIyOX0.g90RxjYHhZJi9XVF1ZMYJQZu_rbUDXtPV77AjuE-HEU",
        "expiresIn": 86400
    }
}
```

{% endtab %}
{% endtabs %}

## Refresh Access Wallet Token

<mark style="color:green;">`POST`</mark> `https://api.console.staging-api.eyowo.com/v1/users/accessToken`

`Usage: { "refreshToken": "5d1a....." }`

#### Headers

| Name      | Type   | Description |
| --------- | ------ | ----------- |
| X-App-Key | string | `X-App-Key` |

#### Request Body

| Name         | Type   | Description                   |
| ------------ | ------ | ----------------------------- |
| refreshToken | string | `wallet refresh access token` |

{% tabs %}
{% tab title="200 Wallet-Access-Token refreshed successfully." %}

```
{
    "success": true,
    "data": {
        "accessToken": "kyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZDI6IjVkMWE4YjEzZjliZTJiNmE2MmUwZDEwMyIsIm1vYmlsZSI6IjIzNDgxODQyMDkxODgiLCJpYXQiOjE1NjI1MzMwNDEsImV4cCI6MTU2MjYxOTQ0MX0.qyZqwrmIIMLloPGbL9q-3O64nQwYNg5DtzDE7B776dQ",
        "expiresIn": 86400
    }
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}

## Note

A user's wallet access token expires after a day. You might need to refresh the wallet to maintain access to the account.
{% endhint %}