Authentication

Authenticate Switch API requests with HTTP Basic Authentication by sending your appId as the username and your appKey as the password.

Switch currently supports one authentication scheme: HTTP Basic Authentication.

After you configure authentication, review Requests for URL, parameter, pagination, and request-body conventions, then use Testing & Debugging Overview to validate your credentials.

Before you start

Get your appId and appKey from the My Organizations page in Dash by Arcadia.
Use your appId as the Basic Auth username.
Use your appKey as the Basic Auth password.
Test your credentials with Testing & Debugging Overview before calling Switch resource APIs. Use Echo Hello for a quick authenticated request.

Configure Basic authentication

Provide your appId and appKey as part of the request, typically through HTTP headers. The appId is the unique ID of your application and is immutable. The appKey is a secret value that you should refresh periodically. Both are available on the My Organizations page of Dash by Arcadia.

To authenticate, pass 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. Format the two together as the string appId:appKey and base64-encode it. Then add it as the Authorization HTTP header. The resulting header looks like this:

Authorization: Basic bXl1c2VyOm15cGFzc3dvcmQ=

Most languages and REST client libraries include helper utilities for adding Basic Auth headers.

The examples below use APP_ID as the app ID and APP_KEY as the app key. Each example makes a request to the Echo Hello endpoint so you can confirm that authentication works.

cURL

curl -u APP_ID:APP_KEY https://api.genability.com/rest/echo/hello

A successful request returns a JSON response similar to this:

{"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.

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 Arcadia API implements the CORS standard, which allows you to make cross-origin JavaScript requests in the browser. This example uses Fetch.

var appId = 'APP_ID';
var appKey = 'APP_KEY';

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

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 and AJAX

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

<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 with this example.

var https = require("https");

var appId = "APP_ID";
var appKey = "APP_KEY";
var credentials = Buffer.from(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 example in a file called example.js returns the following response.

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

Python

This example uses the Python requests package.

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

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

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

PHP

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

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

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

This example uses cURL.

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

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

Next steps

Review Requests to build URLs, parameters, and request bodies correctly.
Review Responses to handle success and error payloads.
Use Testing & Debugging Overview to validate credentials, test input formats, and simulate errors before calling resource APIs.