MSISDN Gateway API v1.0¶
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.
HTTP APIs¶
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
Authentication¶
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.
APIs¶
GET /¶
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" }
POST /register¶
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)
POST /unregister¶
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)
POST /discover¶
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)
POST /sms/mt/verify¶
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)
POST /sms/verify_code¶
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)
POST /certificate/sign¶
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)
GET /.well-known/browserid¶
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" } }
GET /api-specs¶
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" } }
SMS /sms/momt/verify¶
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)
Error Responses¶
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:
404 : unknown URL or unsupported application.
400 : malformed request. Possible causes include a missing option, bad values or malformed json.
401 : you need to be authenticated
- 403 : you are authenticated but don’t have access to the resource you are
requesting.
405 : unsupported method
406 : unacceptable - the client asked for an Accept we don’t support
503 : service unavailable (provider or database backends may be down)
Also the associated errno can be one of:
- 105 INVALID_CODE: This come with a 404 on a wrong validation code;
- 106 BADJSON: This come with a 406 if the sent JSON is not parsable;
- 107 INVALID_PARAMETERS: This come with a 400 and describe invalid parameters with a reason;
- 108 MISSING_PARAMETERS: This come with a 400 and list all missing parameters;
- 109 INVALID_REQUEST_SIG: This come with a 401 and define a problem with the Hawk hash;
- 110 INVALID_AUTH_TOKEN: This come with a 401 and define a problem during Auth;
- 111 EXPIRED: This come with a 410 and define a EXPIRE ressource;
- 112 LENGTH_MISSING: This come with a 411 and defined a missing Content-Length header.
- 113 REQUEST_TOO_LARGE: This come with a 400 and define a too large request;
- 201 BACKEND: This come with a 503 when a third party is not available at the moment.