Generate the signature

In order to properly make any request to Flowroute API, you must generate the HMAC-SHA1 hexdigest (RFC 2104) on a message string. At a high level, the computation can be expressed as follows:

signature = hex(hmac_sha1(API_secret_key, message_string)

Generate the message string

The message string is composed of certain details of the API request. It is formatted as a sequence of tokens separated by newline characters (\n). The sequence is shown in the following table:

Token: Example

Notes

Timestamp
015-09-05T21:29:22Z
The date and time, to the second, of the message. This must be the same timestamp, precise to the second, used in the X-Timestamp header.
HTTP Method
GET, PUT, POST, or PATCH.
The type of action applied to the message. This must be the same HTTP method used in the header.
MD5 Body Hash
ea63c300c845f3e76d8f5827aa0a1f89
The message-digest algorithm (MD5). This must always be computed for the PUT, POST and PATCH HTTP methods. If the body is empty for these methods then the MD5 should be computed on an empty string. For GET methods this token must be blank.
Canonical Request URI
https://api.flowroute.com/v1/example/14045551212\n
See Canonical Request-URI below for instructions on preparing the request.

The concatenated example of the message_string from above, using the PUT HTTP method should resemble:

2015-09-05T21:29:22Z\n
PUT\n
ea63c300c845f3e76d8f5827aa0a1f89\n
https://api.flowroute.com/v1/example/14045551212\n

            

Add the X-Timestamp to the HTTP Request

You must ensure that you add a UTC timestamp in theX-Timestampheader of the HTTP request. This will help to prevent a replay attack, a type of network attack. The value must be the current timestamp in the UTC timezone, precise to the second and formatted according to ISO 8601:

X-Timestamp: 2015-09-05T21:29:22Z

This timestamp in the X-Timestamp header must be the same exact timestamp used in generate the signature.

Canonical Request-URI

The Canonical Request-URI is a string that represents the request in a stable way. Two requests with the same meaning, i.e., reordered query parameters, are represented by the same Canonical Request-URI. It is constructed as follows:

canonical_ruri = url_scheme + "://" + net_location + path + "\n" + ordered_query_params xx", "111"], ["msg", "hello,world"]]

Theordered_query_paramsnames and values should be encoded as they would be in the URL; i.e., they should use URL-plus encoding. For example, a space should be replaced with a plus [+].

Request URI Field Example Description
url_scheme https The secure protocol to use. HTTPS is always used for the live API.
net_location api.flowroute.com The requested domain.
path /available-tns/tns/ URL to the requested resource—for example, /available-tns/tns.
"\n" \n Inserts an escape sequence, or a new line.
ordered_query_params [["nxx", "222"], ["npa", "111"], ["nxx", "111"], ["msg", "hello,world"]] GET query parameters, ordered first by name and then by value.
Example

In the following example, if URI field values are as follows,

  • url_scheme = https
  • net_location = api.flowroute.com
  • path = /available-tns/tns/
  • query_parameters = [["nxx", "222"], ["npa", "111"], ["nxx", "111"], ["msg", "hello,world"]]

then the Canonical Request-URI after assembling the tokens and ordering and encoding the query parameters would be:

https://api.flowroute.com/available-tns/tns/npa=111&nxx=111&nxx=222&msg=hello%2Cworld

Character Encoding

Use UTF-8 character encoding for the query parameters before URL-encoding them.