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

Simple Authentication

This is the solely supported authentication scheme at this time. You need to supply an appId and appKey as part of the request either via headers or the query string (more info below). 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 Manage Apps page of Genability Explorer.

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 Hello endpoint.


> curl -u APP_ID:APP_KEY
{"status":"success","count":1,"type":null,"results":["Hello World","Hello World!"]}


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.

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();
                new AuthScope("", 443),
                new UsernamePasswordCredentials("APP_ID", "APP_KEY"));
        CloseableHttpClient httpclient = HttpClients.custom()
        try {
            HttpGet httpget = new HttpGet("");

            System.out.println("Executing request " + httpget.getRequestLine());
            CloseableHttpResponse response = httpclient.execute(httpget);
            try {
            } finally {
        } finally {

JavaScript (Browser)

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

    <script src=""></script>
  <p id="text">Some Text</p>
  <button id="btn">Click</button>

   var appId = "APP_ID"
   var appKey = "APP_KEY"

   $("#btn").click(function(e) {
       $.ajax("", {
           headers: {
               "Authorization": "Basic: " + btoa(appId + ":" + appKey)
           success: function(data, status, xhr) {

JavaScript (Node.js)

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: "",
    path: "/rest/echo/hello",
    headers: {
        "Authorization": auth

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

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

    res.on("end", function() {

https.get(options, after);
> node example.js
{"status":"success","count":1,"type":null,"results":["Hello World","Hello World!"]}


This example uses the requests package.

>>> import requests
>>> response = requests.get("", auth=("APP_ID", "APP_KEY"))
>>> print(response.text)
{"status":"success","count":1,"type":null,"results":["Hello World","Hello World!"]}


This example uses the httpclient gem.

require 'httpclient'

appId = "APP_ID"
appKey = "APP_KEY"
domain = ""

http =
http.set_auth(domain, appId, appKey)
response = http.get_content("")

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


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.

    $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("", false, $context));
> php example.php
{"status":"success","count":1,"type":null,"results":["Hello World","Hello World!"]}

This example uses cURL.

$url = "";

$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); 

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