<commit_before># MSISDN Verification API

This document provides protocol-level and usage details for the Mozilla MSISDN Verification API.

# Obtaining the MSISDN

### Getting it from the SIM card

It is possible to obtain the MSISDN from the SIM card if this value is filled
by the operator. However, this is not the general case and many operators
doesn't write this value to the SIM. In any case, even if it is available this
field can be modified by the user at any time and so it cannot be trusted
without a proper verification.

### SMS-MO

Another mechanism to obtain the MSISDN is by asking the device to send an
SMS-MO (Mobile Originated) message to a specific phone number or short code.
This requires support from the operator in order to make sure that the SMS is
charge-free for the user.

### Asking the user

This is the fallback if all the above options are not available.

# Verification mechanisms

### Network based authentication

Some operators may support a network-based authentication mechanism where the
device is authenticated by making an http request to the authentication server
over the device's mobile data connection such that the carrier injects a header
which contains a token that can be used to verify the users MSISDN.

This kind of authentication mechanism does not require us to provide an MSISDN
in advance and so the whole flow can be done without user interaction.

### SMS based authentication

#### SMS-MT only

In an SMS-MT (Mobile Terminated) only based authentication the verification
server is given an MSISDN to send an SMS with a verification code and the
device makes an http request to give the verification code back to the server
as a proof of ownership.

This requires us to provide an MSISDN in advance and so the flow might require
user interaction.

It is also possible that the given MSISDN does not belong to the device from
where the requests to the verification server are done and so the SMS will be
received by another device. In that case, the user will need to manually enter
the verification code. This is the scenario for an MSISDN verification
triggered by a desktop client.

#### SMS-MO and SMS-MT

In an SMS-MO (Mobile Originated) + SMS-MT (Mobile Terminated) based
authentication, the device sends an SMS to the verification server which
replies back with a SMS verification code that must be given back to the server
as a proof of ownership.

This mechanism does not require us to provide an MSISDN in advance and so the
flow can be done without user interaction.

This flow requires support from the operator to assure that the phone number or
the short code that the device uses to send the SMS-MO is free of charge for
the user.

### Telephony call based authentication

# Flows

## SMS MT

<img src="http://www.gliffy.com/go/publish/image/5685727/L.png" />

## SMS MO + MT

<img src="http://www.gliffy.com/go/publish/image/5685725/L.png" />

# API Endpoints
  * [POST /v1/msisdn/register](#post-v1msisdnregister)
  * [POST /v1/msisdn/unregister](#post-v1msisdnunregister) :lock:
  * [POST /v1/msisdn/sms/mt/verify](#post-v1msisdnsmsmtverify) :lock:
  * [SMS  /v1/msisdn/sms/momt/verify](#sms-v1msisdnsmsmomtverify)
  * [POST /v1/msisdn/sms/verify_code](#post-v1msisdnverify_code) :lock:

## POST /v1/msisdn/discover

For the given network information (msisdn, mcc, mnc and roaming), the verification service returns a list of available verification methods and the corresponding details.

### Request

```sh
curl -v \
-X POST \
-H "Content-Type: application/json" \
"https://msisdn.accounts.firefox.com/v1/msisdn/discover" \
-d '{
  "msisdn": "+442071838750"
  "mcc": "214",
  "mnc": "07",
  "roaming": false
}'
```

___Parameters___
* `msisdn` - a MSISDN in E.164 format. Providing an MSISDN is optional as the
  client might not know it in advance but allows the server to decide which
  verification mechanism to use in a better way. For instance, if an MSISDN is
  provided, even if an SMS MO + MT flow is possible an SMS MT only flow should
  be chosen by the server instead.
* `mcc` - [Mobile Country Code](http://es.wikipedia.org/wiki/MCC/MNC)
* `mnc` - [Mobile Network Code](http://es.wikipedia.org/wiki/MCC/MNC)
* `roaming` - boolean that indicates if the device is on roaming or not

### Response

Successful requests will produce a "200 OK" response with following format:

```json
{
  "verificationMethods": [ "sms:momt", "sms:mt" ],
  "verificationDetails": {
    "sms:mt": {
      "mtSender": "123"
    },
    "sms:momt": {
      "mtSender": "123",
      "moVerifier": "234"
    }
  }
}
```

* `verificationMethods` - a list of verification methods available for the given set of parameters
* `verificationDetails` - an object whose keys are the elements of `verificationMethods` and whose values are the details of each method

Failing requests may be due to the following errors:

* status code 400, errno 106: request body was not valid json
* status code 400, errno 107: request body contains invalid parameters
* status code 400, errno 108: request body missing required parameters
* status code 411, errno 112: content-length header was not provided
* status code 413, errno 113: request body too large
* status code 429, errno 114: client has sent too many requests
* status code 503, errno 201: service temporarily unavailable to due high load

## POST /v1/msisdn/register

Starts a MSISDN registration session.

### Request

```sh
curl -v \<commit_msg>Added /discover to list of API endpoints and added documentation that the verification methods are returned in preferred order.<commit_after># MSISDN Verification API

This document provides protocol-level and usage details for the Mozilla MSISDN Verification API.

# Obtaining the MSISDN

### Getting it from the SIM card

It is possible to obtain the MSISDN from the SIM card if this value is filled
by the operator. However, this is not the general case and many operators
doesn't write this value to the SIM. In any case, even if it is available this
field can be modified by the user at any time and so it cannot be trusted
without a proper verification.

### SMS-MO

Another mechanism to obtain the MSISDN is by asking the device to send an
SMS-MO (Mobile Originated) message to a specific phone number or short code.
This requires support from the operator in order to make sure that the SMS is
charge-free for the user.

### Asking the user

This is the fallback if all the above options are not available.

# Verification mechanisms

### Network based authentication

Some operators may support a network-based authentication mechanism where the
device is authenticated by making an http request to the authentication server
over the device's mobile data connection such that the carrier injects a header
which contains a token that can be used to verify the users MSISDN.

This kind of authentication mechanism does not require us to provide an MSISDN
in advance and so the whole flow can be done without user interaction.

### SMS based authentication

#### SMS-MT only

In an SMS-MT (Mobile Terminated) only based authentication the verification
server is given an MSISDN to send an SMS with a verification code and the
device makes an http request to give the verification code back to the server
as a proof of ownership.

This requires us to provide an MSISDN in advance and so the flow might require
user interaction.

It is also possible that the given MSISDN does not belong to the device from
where the requests to the verification server are done and so the SMS will be
received by another device. In that case, the user will need to manually enter
the verification code. This is the scenario for an MSISDN verification
triggered by a desktop client.

#### SMS-MO and SMS-MT

In an SMS-MO (Mobile Originated) + SMS-MT (Mobile Terminated) based
authentication, the device sends an SMS to the verification server which
replies back with a SMS verification code that must be given back to the server
as a proof of ownership.

This mechanism does not require us to provide an MSISDN in advance and so the
flow can be done without user interaction.

This flow requires support from the operator to assure that the phone number or
the short code that the device uses to send the SMS-MO is free of charge for
the user.

### Telephony call based authentication

# Flows

## SMS MT

<img src="http://www.gliffy.com/go/publish/image/5685727/L.png" />

## SMS MO + MT

<img src="http://www.gliffy.com/go/publish/image/5685725/L.png" />

# API Endpoints
  * [POST /v1/msisdn/discover](#post-v1msisdndiscover)
  * [POST /v1/msisdn/register](#post-v1msisdnregister)
  * [POST /v1/msisdn/unregister](#post-v1msisdnunregister) :lock:
  * [POST /v1/msisdn/sms/mt/verify](#post-v1msisdnsmsmtverify) :lock:
  * [SMS  /v1/msisdn/sms/momt/verify](#sms-v1msisdnsmsmomtverify)
  * [POST /v1/msisdn/sms/verify_code](#post-v1msisdnverify_code) :lock:

## POST /v1/msisdn/discover

For the given network information (msisdn, mcc, mnc and roaming), the verification service returns a list of available verification methods and the corresponding details.

### Request

```sh
curl -v \
-X POST \
-H "Content-Type: application/json" \
"https://msisdn.accounts.firefox.com/v1/msisdn/discover" \
-d '{
  "msisdn": "+442071838750"
  "mcc": "214",
  "mnc": "07",
  "roaming": false
}'
```

___Parameters___
* `msisdn` - a MSISDN in E.164 format. Providing an MSISDN is optional as the
  client might not know it in advance but allows the server to decide which
  verification mechanism to use in a better way. For instance, if an MSISDN is
  provided, even if an SMS MO + MT flow is possible an SMS MT only flow should
  be chosen by the server instead.
* `mcc` - [Mobile Country Code](http://es.wikipedia.org/wiki/MCC/MNC)
* `mnc` - [Mobile Network Code](http://es.wikipedia.org/wiki/MCC/MNC)
* `roaming` - boolean that indicates if the device is on roaming or not

### Response

Successful requests will produce a "200 OK" response with following format:

```json
{
  "verificationMethods": [ "sms:momt", "sms:mt" ],
  "verificationDetails": {
    "sms:mt": {
      "mtSender": "123"
    },
    "sms:momt": {
      "mtSender": "123",
      "moVerifier": "234"
    }
  }
}
```

* `verificationMethods` - a list of verification methods available for the given set of parameters, in order of preferred use
* `verificationDetails` - an object whose keys are the elements of `verificationMethods` and whose values are the details of each method

The methods listed in `verificationMethods` are sorted in the preferred order from the perspective of the server, i.e., the method listed first is the most preferred method. 

Failing requests may be due to the following errors:

* status code 400, errno 106: request body was not valid json
* status code 400, errno 107: request body contains invalid parameters
* status code 400, errno 108: request body missing required parameters
* status code 411, errno 112: content-length header was not provided
* status code 413, errno 113: request body too large
* status code 429, errno 114: client has sent too many requests
* status code 503, errno 201: service temporarily unavailable to due high load

## POST /v1/msisdn/register

Starts a MSISDN registration session.

### Request

```sh
curl -v \
{'fraction_non_alphanumeric': 0.07307555870876198, 'fraction_numerical': 0.018091521816246896, 'mean_word_length': 4.123580190822353, 'pattern_counts': {'":': 22, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 2, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3963515', 'n_tokens_mistral': 3417, 'n_tokens_neox': 3163, 'n_words': 1578}