Security

We currently support a single authentication scheme, which we call the “simple” approach.

Simple Authentication

Supply your appId and appKey as part of the request either via HTTP header. The appId is the unique ID of your application and is immutable. The appKey is something you can and should refresh periodically. Both are available on the My Applications page of Dash by Genability.

To authenticate, pass in your appId and appKey in the request header. This is the standard HTTP Basic authentication scheme with your appId as the username and appKey as the password. You simply format the two together as the string appId:appKey and base64-encode it. Then add it as the Authorization HTTP Header. The resulting header will look like this:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Most languages and REST client libraries have helper utilities to make adding this a snap.

Here are some examples of authenticating to the Genability API in various languages and frameworks. For these examples, we’ll assume that our app id is APP_ID and our app key is APP_KEY. We’ll make a simple request to the Echo Hello endpoint.

cURL

> curl -u APP_ID:APP_KEY https://api.genability.com/rest/echo/hello
{"status":"success","count":1,"type":null,"results":["Hello World","Hello World!"]}

Java

If you are developing in Java, We recommend using our Java client library. It handles all of the authenticating and request building for you. If you can’t use our library, we have an example of how to authenticate below.

This example uses the Apache HttpClient library. It is adapted from one of their samples.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
import org.apache.http.auth.AuthScope;
import org.apache.http.auth.UsernamePasswordCredentials;
import org.apache.http.client.CredentialsProvider;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.BasicCredentialsProvider;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

public class GenabilityAuthentication {

    public static void main(String[] args) throws Exception {
        CredentialsProvider credsProvider = new BasicCredentialsProvider();
        credsProvider.setCredentials(
                new AuthScope("api.genability.com", 443),
                new UsernamePasswordCredentials("APP_ID", "APP_KEY"));
        CloseableHttpClient httpclient = HttpClients.custom()
                .setDefaultCredentialsProvider(credsProvider)
                .build();
        try {
            HttpGet httpget = new HttpGet("https://api.genability.com/rest/echo/hello");

            System.out.println("Executing request " + httpget.getRequestLine());
            CloseableHttpResponse response = httpclient.execute(httpget);
            try {
                System.out.println("----------------------------------------");
                System.out.println(response.getStatusLine());
                EntityUtils.consume(response.getEntity());
            } finally {
                response.close();
            }
        } finally {
            httpclient.close();
        }
    }
}

JavaScript (Browser using Fetch)

The Genability API implements the CORS standard, which allows you to make cross-origin JavaScript requests in the browser. This example uses Fetch (good intro to Fetch here).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
var appId = 'APP_ID';
var appKey = 'APP_KEY';

var url = 'https://api.genability.com/rest/echo';

fetch(url, {
    method: 'get',
    headers: {
      "Authorization": "Basic: " + btoa(appId + ":" + appKey)
    }
  })
  .then(function(response) {
    if (response.status !== 200) {
      console.log('Request Status not 200');
      console.log(response.status);
      return;
    }
    response.json().then(function(data) {
      console.log('Request succeeded with JSON response');
      console.log(JSON.stringify(data));
    });
    
  })
  .catch(function(error) {
    console.log('Request errored');
    console.log(error);
  });

JavaScript (Browser using jquery + AJAX)

As mentioned, the Genability API implements the CORS standard, which allows you to make cross-origin JavaScript requests in the browser. This example uses jQuery.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
<html>
  <head>
    <script src="https://code.jquery.com/jquery-1.11.3.min.js"></script>
  </head>
  <p id="text">Some Text</p>
  <button id="btn">Click</button>

  <script>
   var appId = "APP_ID"
   var appKey = "APP_KEY"
   
   $("#btn").click(function(e) {
       $.ajax("https://api.genability.com/rest/echo/hello", {
           headers: {
               "Authorization": "Basic: " + btoa(appId + ":" + appKey)
           },
           success: function(data, status, xhr) {
               $("#text").text(JSON.stringify(data));
           }
       });
   });
  </script>
</html>

JavaScript (Node.js)

If you are running Javascript on a Node.js server, you can authenticate like this example.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
var https = require("https");

var appId = "APP_ID";
var appKey = "APP_KEY";
var credentials = new Buffer(appId + ":" + appKey).toString("base64");
var auth = "Basic " + credentials

var options = {
    hostname: "api.genability.com",
    path: "/rest/echo/hello",
    headers: {
        "Authorization": auth
    }
}

function after(res) {
    var body = "";

    res.on("data", function(d) {
        body += d;
    });

    res.on("end", function() {
        console.log(body);
    });
}

https.get(options, after);

Running the above in a file called example.js would give you the following.

1
2
> node example.js
{"status":"success","count":1,"type":null,"results":["Hello World","Hello World!"]}

Python

This example uses the Python requests package.

1
2
3
4
>>> import requests
>>> response = requests.get("https://api.genability.com/rest/echo/hello", auth=("APP_ID", "APP_KEY"))
>>> print(response.text)
{"status":"success","count":1,"type":null,"results":["Hello World","Hello World!"]}

Ruby

This example uses the Ruby httpclient gem.

1
2
3
4
5
6
7
8
9
10
11
require 'httpclient'

appId = "APP_ID"
appKey = "APP_KEY"
domain = "https://api.genability.com"

http = HTTPClient.new
http.set_auth(domain, appId, appKey)
response = http.get_content("https://api.genability.com/rest/echo/hello")

puts response

1
2
> ruby example.rb
{"status":"success","count":1,"type":null,"results":["Hello World","Hello World!"]}

PHP

There are a few different ways to accomplish this in PHP. This first example uses a request context to set the username and password for a file_get_contents call.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<?php
    $appId = 'APP_ID';
    $appKey = 'APP_KEY';
	$auth = base64_encode($appId . ':' . $appKey);

    $options = array(
		'http' => array(
			'method' => "GET",
			'header' => 'Authorization: Basic ' . $auth
		)
	);
	
	$context = stream_context_create($options);
    print(file_get_contents("https://api.genability.com/rest/echo/hello", false, $context));
?>

1
2
> php example.php
{"status":"success","count":1,"type":null,"results":["Hello World","Hello World!"]}

This example uses cURL.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<?php
$url = "https://api.genability.com/rest/echo/hello";

$appId = "APP_ID";
$appKey = "APP_KEY";

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_USERPWD, $appId . ":" . $appKey);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); 
$resp = curl_exec($ch); 
curl_close($ch);

print($resp);
?>

1
2
> php example-curl.php
{"status":"success","count":1,"type":null,"results":["Hello World","Hello World!"]}