This document is based on the current status of the server. All the examples had been done with real calls. It doesn’t reflect any future implementation and tries to stick with the currently deployed version.
This document describes the HTTP API and the SMS API.
Note
Unless stated otherwise, all APIs are using application/json for the requests and responses content types. Parameters for the GET requests are form encoded (?key=value&key2=value2)
To ease testing, you can use httpie in order to make requests. Examples of use with httpie are provided when possible. In order to authenticate with hawk, you’ll need to install the requests-hawk module
To deal with authentication, the MSISDN Gateway server uses Hawk sessions. When you register, you can do so with different authentications schemes, but you are always given an hawk session back, that you should use when requesting the endpoints which need authentication.
When authenticating using the /register endpoint, you will be given an hawk session token called msisdnSessionToken in the body. You will need to derive as explained at Derive hawk credentials from the hawk session token.
Displays version information, for instance:
http GET localhost:5000 --verboseGET / HTTP/1.1 Accept: application/json Accept-Encoding: gzip, deflate Content-Type: application/json; charset=utf-8 Host: localhost:5000 User-Agent: HTTPie/0.8.0 HTTP/1.1 200 OK Access-Control-Allow-Credentials: true Connection: keep-alive Content-Length: 219 Content-Type: application/json; charset=utf-8 Date: Mon, 28 Jul 2014 13:52:16 GMT ETag: W/"db-3773650714" Timestamp: 1406555536 { "description": "The Mozilla MSISDN Gateway", "endpoint": "http://localhost:5000", "homepage": "https://github.com/mozilla-services/msisdn-gateway/", "name": "mozilla-msisdn-gateway", "version": "0.5.0" }
Creates a new msisndSessionToken associated with an Hawk session.
This is the first step to start verifying a new number.
Example:
http POST localhost:5000/register --verbosePOST /register HTTP/1.1 Accept: */* Accept-Encoding: gzip, deflate Content-Length: 0 Host: localhost:5000 User-Agent: HTTPie/0.8.0 HTTP/1.1 200 OK Access-Control-Allow-Credentials: true Connection: keep-alive Content-Length: 94 Content-Type: application/json; charset=utf-8 Date: Mon, 28 Jul 2014 13:55:20 GMT Timestamp: 1406555720 { "msisdnSessionToken": "8feb2f78227ff8f8d4addd8ba77c06d9ee7acb59d86bd78ae2fd94e242dfd1ee" }Server should acknowledge your request, return a msisdnSessionToken and answer with a status code of 200 OK.
Potential HTTP error responses include:
- 429 Too Many Requests: Client has sent too many requests (errno: 117)
- 503 Service Unavailable: Service temporarily unavailable due to high load or misconfiguration of the storage backend. (errno: 201)
Requires authentication
Unregister an Hawk session.
To revoke a device or once we don’t want to use this validation number anymore, we can unregister the session token to prevent the user from continuing to generate BrowserID certificates with it.
Example:
http POST localhost:5000/unregister --verbose \ --auth-type=hawk \ --auth='8feb2f78227ff8f8d4addd8ba77c06d9ee7acb59d86bd78ae2fd94e242dfd1ee:'POST /unregister HTTP/1.1 Accept: */* Accept-Encoding: gzip, deflate Authorization: Hawk mac="Tpny...a+A=", hash="B0we...z8=", id="bc...2f", ts="1406556506", nonce="E_GRLT" Content-Length: 0 Host: localhost:5000 User-Agent: HTTPie/0.8.0 HTTP/1.1 204 No Content Access-Control-Allow-Credentials: true Connection: keep-alive Date: Mon, 28 Jul 2014 14:08:26 GMT Server-Authorization: Hawk mac="lTGx...PNM=", hash="B0we...Uz8="Server should acknowledge your request and answer with a status code of 204 No Content.
Potential HTTP error responses include:
- 401 Unauthorized: The credentials you passed aren’t valid. (errno: 109 or 110)
- 429 Too Many Requests: Client has sent too many requests (errno: 117)
- 503 Service Unavailable: Service temporarily unavailable due to high load or misconfiguration of the storage backend. (errno: 201)
Discover which validation methods are available for a given MSISDN number or a MCC/MNC network-code.
Body parameters:
- mcc, the Mobile Country Code.
- mnc, the Mobile Network Code (optional).
- msisdn, the Mobile Station ISDN Number that is the user phone number to validate in its international form i.e 33623456789 (optional).
Example (with MCC only):
http POST localhost:5000/discover mcc=208 --verbosePOST /discover HTTP/1.1 Accept: application/json Accept-Encoding: gzip, deflate Content-Length: 14 Content-Type: application/json; charset=utf-8 Host: localhost:5000 User-Agent: HTTPie/0.8.0 { "mcc": "214" } HTTP/1.1 200 OK Access-Control-Allow-Credentials: true Connection: keep-alive Content-Length: 169 Content-Type: application/json; charset=utf-8 Date: Mon, 28 Jul 2014 14:18:05 GMT Timestamp: 1406557085 { "verificationDetails": { "sms/momt": { "moVerifier": "+34191600777", "mtSender": "Mozilla@" } }, "verificationMethods": [ "sms/momt" ] }Example (with all parameters):
http POST localhost:5000/discover msisdn=+3412578946 mcc=208 mnc=07 --verbosePOST /discover HTTP/1.1 Accept: application/json Accept-Encoding: gzip, deflate Content-Length: 51 Content-Type: application/json; charset=utf-8 Host: localhost:5000 User-Agent: HTTPie/0.8.0 { "mcc": "214", "mnc": "07", "msisdn": "3412578946" } HTTP/1.1 200 OK Access-Control-Allow-Credentials: true Connection: keep-alive Content-Length: 286 Content-Type: application/json; charset=utf-8 Date: Mon, 28 Jul 2014 14:20:07 GMT Timestamp: 1406557207 { "verificationDetails": { "sms/momt": { "moVerifier": "+34191600777", "mtSender": "Mozilla@" }, "sms/mt": { "mtSender": "Mozilla@", "url": "http://localhost:5000/sms/mt/verify" } }, "verificationMethods": [ "sms/mt", "sms/momt" ] }Response from the server:
The server should answer this with a 200 OK status code and a JSON object with the following properties:
- 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.
Potential HTTP error responses include:
- 400 Bad Request: MCC, MNC or MSISDN missing (errno: 108) or invalids (errno: 107)
- 406 Bad JSON: The body is not valid JSON. (errno: 106)
- 411 Length Required: Content-Length header wasn’t provided. (errno: 112)
- 413 Request Too Large: Request Too Large. (errno: 113)
- 429 Too Many Requests: Client has sent too many requests (errno: 117)
- 503 Service Unavailable: Service temporarily unavailable due to high load or misconfiguration of the storage backend. (errno: 201)
Requires authentication
Starts the SMS MT flow by sending a SMS to the MSISDN to register
Body parameters:
- msisdn, the Mobile Station ISDN Number that is the user phone number to validate in its international form i.e +33623456789.
- mcc, the Mobile Country Code.
- mnc, the Mobile Network Code (optional).
- shortVerificationCode, a parameter to ask a human transcribable 6 digits code if set to true. In that case the server will also take care of the Accept-Language header to localize any text in the SMS (optional)
Response from the server:
The server should answer this with a 204 No Content status code.
Example:
http POST localhost:5000/sms/mt/verify msisdn=+33123456789 mcc=208 \ --verbose \ --auth-type=hawk \ --auth='8feb2f78227ff8f8d4addd8ba77c06d9ee7acb59d86bd78ae2fd94e242dfd1ee:'POST /sms/mt/verify HTTP/1.1 Accept: application/json Accept-Encoding: gzip, deflate Authorization: Hawk mac="THYl...=", hash="mw68...=", id="9ee4...1a81", ts="1406557901", nonce="xoIdtg" Content-Length: 53 Content-Type: application/json; charset=utf-8 Host: localhost:5000 User-Agent: HTTPie/0.8.0 { "mcc": "208", "msisdn": "+33123456789" } HTTP/1.1 204 No Content Access-Control-Allow-Credentials: true Connection: keep-alive Date: Mon, 28 Jul 2014 14:31:41 GMT Server-Authorization: Hawk mac="wx9m...=", hash="B0we...="Potential HTTP error responses include:
- 400 Bad Request: MCC, MNC or MSISDN missing (errno: 108) or invalids (errno: 107)
- 406 Bad JSON: The body is not valid JSON. (errno: 106)
- 411 Length Required: Content-Length header wasn’t provided. (errno: 112)
- 413 Request Too Large: Request too large. (errno: 113)
- 429 Too Many Requests: Client has sent too many requests (errno: 117)
- 503 Service Unavailable: Service temporarily unavailable due to high load or misconfiguration of the storage backend. (errno: 201)
Requires authentication
Validates the code received by SMS
Body parameters:
- code, the code received by SMS.
Response from the server:
The server should answer this with a 200 OK status code and a JSON object with the following properties:
- msisdn The Mobile phone number that has been validated during the session.
Example:
http POST localhost:5000/sms/verify_code code=15d3b227b0e58f216ee49b8da41c05c8 \ --verbose \ --auth-type=hawk \ --auth='c0d8cd2ec579a3599bef60f060412f01f5dc46f90465f42b5c47467481315f51:'POST /sms/verify_code HTTP/1.1 Accept: application/json Accept-Encoding: gzip, deflate Authorization: Hawk mac="8/Rg...=", hash="oAXy...=", id="9ee4...1a81", ts="1406558280", nonce="WBjO3I" Content-Length: 44 Content-Type: application/json; charset=utf-8 Host: localhost:5000 User-Agent: HTTPie/0.8.0 { "code": "15d3b227b0e58f216ee49b8da41c05c8" } HTTP/1.1 200 OK Access-Control-Allow-Credentials: true Connection: keep-alive Content-Length: 30 Content-Type: application/json; charset=utf-8 Date: Mon, 28 Jul 2014 14:38:00 GMT Server-Authorization: Hawk mac="nFOD...=", hash="NVuB...=" Timestamp: 1406558280 { "msisdn": "+33123456789" }Potential HTTP error responses include:
- 400 Bad Request: code missing (errno: 108) or invalid (errno: 105)
- 406 Bad JSON: the body is not valid JSON. (errno: 106)
- 410 Expired: the session MSISDN has expired. (errno: 111)
- 411 Length Required: Content-Length header wasn’t provided. (errno: 112)
- 413 Request Too Large: Request too large. (errno: 113)
- 429 Too Many Requests: Client has sent too many requests (errno: 117)
- 503 Service Unavailable: Service temporarily unavailable due to high load or misconfiguration of the storage backend. (errno: 201)
Requires authentication
Generate a BrowserID certificate with the given public key for the validated number.
Example:
http POST localhost:5000/certificate/sign \ duration=3600 \ publicKey='{"algorithm":"DS","y":"e6...40","p":"d6...01","q":"b1...3b","g":"9a...ef"}' \ --verbose \ --auth-type=hawk \ --auth='8feb2f78227ff8f8d4addd8ba77c06d9ee7acb59d86bd78ae2fd94e242dfd1ee:'POST /certificate/sign HTTP/1.1 Accept: application/json Accept-Encoding: gzip, deflate Authorization: Hawk mac="6vKD...=", hash="PKZT...=", id="9e...81", ts="1406558679", nonce="IFjRIR" Content-Length: 1702 Content-Type: application/json; charset=utf-8 Host: localhost:5000 User-Agent: HTTPie/0.8.0 { "duration": "3600", "publicKey": "{\"algorithm\":\"DS\",\"y\":\"e6...40\",\"p\":\"d6...01\",\"q\":\"b1...3b\",\"g\":\"9a...ef\"}" } HTTP/1.1 200 OK Access-Control-Allow-Credentials: true Connection: keep-alive Content-Length: 2602 Content-Type: application/json; charset=utf-8 Date: Mon, 28 Jul 2014 14:44:39 GMT Server-Authorization: Hawk mac="QMCs...=", hash="NVuB...=" Timestamp: 1406558679 { "cert": "eyJh...1Rgg" }Potential HTTP error responses include:
- 400 Bad Request: duration or publicKey parameter missing (errno: 108) or invalid (errno: 107)
- 406 Bad JSON: The body is not valid JSON. (errno: 106)
- 411 Length Required: Content-Length header wasn’t provided. (errno: 112)
- 413 Request Too Large: Request Too Large. (errno: 113)
- 429 Too Many Requests: Client has sent too many requests (errno: 117)
- 503 Service Unavailable: Service temporarily unavailable due to high load or misconfiguration of the storage backend. (errno: 201)
Returns information for the BrowserID verifier.
Response from the server:
The server should answer this with a 200 status code and a JSON object with the following properties:
- public-key the server public-key used to validate the BrowserId certificate
- authentication, the link to the authentication page
- provisionning, the link to the provisionning page
Example:
http GET localhost:5000/.well-known/browserid --verboseGET /.well-known/browserid HTTP/1.1 Accept: */* Accept-Encoding: gzip, deflate Host: localhost:5000 User-Agent: HTTPie/0.8.0 HTTP/1.1 200 OK Access-Control-Allow-Credentials: true Connection: keep-alive Content-Length: 1815 Content-Type: application/json; charset=utf-8 Date: Mon, 28 Jul 2014 14:54:50 GMT ETag: W/"717-781509924" Timestamp: 1406559290 { "authentication": "/.well-known/browserid/warning.html", "provisioning": "/.well-known/browserid/warning.html", "public-key": { "algorithm": "DS", "g": "9a...ef", "p": "d6...01", "q": "b1...3b", "y": "7e...b9" } }
An endpoint that gives back the videur configuration.
Server should answer with a status of 200 and the API routes as a JSON object.
Example:
http GET localhost:5000/api-specs --verboseGET /api-specs HTTP/1.1 Accept: */* Accept-Encoding: gzip, deflate Host: localhost:5000 User-Agent: HTTPie/0.8.0 HTTP/1.1 200 OK Access-Control-Allow-Credentials: true Connection: keep-alive Content-Length: 1069 Content-Type: application/json; charset=utf-8 Date: Mon, 28 Jul 2014 14:57:54 GMT ETag: W/"42d-3425668954" Timestamp: 1406559474 { "service": { "location": "http://localhost:5000", "resources": { "/": { "GET": {} }, "/.well-known/browserid": { "GET": {} }, "/.well-known/browserid/warning.html": { "GET": {} }, "/__heartbeat__": { "GET": {} }, "/certificate/sign": { "POST": { "max_body_size": "10k" } }, "/discover": { "POST": { "max_body_size": "10k" } }, "/register": { "POST": { "max_body_size": "10k" } }, "/sms/momt/": { "GET": {}, "POST": { "max_body_size": "10k" } }, "/sms/mt/verify": { "POST": { "max_body_size": "10k" } }, "/sms/verify_code": { "POST": { "max_body_size": "10k" } }, "/unregister": { "POST": { "max_body_size": "10k" } } }, "version": "0.5.0", "videur_version": "0.1" } }
The SMS message to a moVerifier number will start the MOMT flow.
SMS should be of the form of:
/sms/momt/verify <hawkId>i.e:
/sms/momt/verify 9ee442e5c8575c4077db786a40f603a70ae8eee09f5b41e34c096410f6fc1a81
- path, future proof path, in order to be able to route SMS to the right endpoint.
- hawkId, the hawk session id extracted from the msisdnSessionToken using HKDF.
When the SMS Gateway receive the Inbound Message, it will make a call on the configured endpoint.
For Nexmo — GET or POST /sms/momt/?provider=nexmo
Querystring parameters:
- msisdn, the phone number from which the message is coming
- text, the content of the message
- network-code, the MCC/MNC unique identifier
For BeepSend — GET or POST /sms/momt/?provider=beepsend
Querystring or Body parameters:
- from, the phone number from which the message is coming
- message, the content of the message
- mcc, The Mobile Country Code (in GET)
- mnc, The Mobile Network Code (in GET)
- mccmnc, {“mcc”: “<Mobile Country Code>”, “mnc”: “<Mobile Network Code>”} (in POST)
All errors are also returned, wherever possible, as json responses with a code, errno and error message.
Error status codes and codes and their corresponding outputs are:
Also the associated errno can be one of: