CallFire Solutions

Authentication

Follow

Authentication in the CallFire API

When you’re integrating against the CallFire API, it’s handy to be aware of the authentication layer which restricts, or protects, access to it.

It’s important because requests need to be protected, ensuring that no unwanted third-parties can intercept and retrieve your access credentials and impersonate you; thereby either retrieving information from your account, or making changes to it.

In this short post, we’re going to briefly look at the authentication mechanism used, and how to make authenticated requests against it, when integrating against the CallFire API, using Go, Node.js, and Curl.

HTTP Basic Authentication

The authentication layer used is one of the oldest ones around, called HTTP Basic Authentication. Described most simply, basic authentication is:

A method for an HTTP user agent (such as a Browser) to provide a user name and password when making a request.

HTTP Basic Authentication uses HTTP headers to transmit (unencrypted and not hashed) a username and password, colon-separated, and encoded using Base64 encoding. This is an effective, if rudimentary system for implementing authenticated access to a remote service.

However there are drawbacks, such as the HTTP specification not providing for the caching of the credentials supplied. As a result they have to be sent with every request which requires them.

Another important point to also consider, and remember, when using Basic Authentication, is that the information is not encrypted. So it’s never a good idea to use it over standard HTTP, only over HTTPS, which the CallFire API does.

A Simple Example

Now let’s look at a simple, working, example. Let’s say that you were using the username: AuthUser and the password: MyUltraSafePassword. Here’s an example of the header which would be sent after combining the two, with a colon, and Base64 encoding them:

Authorization: Basic QXV0aFVzZXI6TXlVbHRyYVNhZmVQYXNzd29yZA==

If you wanted to try it out, you could use this simple PHP script to encode different combinations of username and password:

<?php
$username = 'AuthUser';
$password = 'MyUltraSafePassword';
print base64_encode("{$username}:{$password}");

If you’d like further information about Basic Authentication, check out this introductory reference on Wikipedia, or some of the links in the further reading section at the end of this post.

Passing the Credentials Securely Using Go

Let’s start by having a look at small example request, using Go. The code example uses the Client object from the net/http library to make a request to the contact endpoint of the CallFire REST API, over https.

It’s a little contrived, but essentially it sets up and makes a connection to https://www.callfire.com/api/1.1/rest/contact, and outputs the body of response received, on success. On failure the reason for the failure is output instead.

But skipping to the key line, you can see on line fourteen, that the SetBasicAuth() method is used to set the username and password which makes a Basic Authentication request.

package main

import (
    "fmt"
    "io/ioutil"
    "log"
    "net/http"
)

func main() {
    client := &http.Client{}

    req, err := http.NewRequest("GET", "https://www.callfire.com/api/1.1/rest/contact", nil)
    req.SetBasicAuth("<username>", "<password>")
    resp, err := client.Do(req)
    if err != nil {
        fmt.Printf("Error : %s", err)
    }

    // Retrieve the body of the response
    body, err := ioutil.ReadAll(resp.Body)
    resp.Body.Close()

    if err != nil {
        log.Fatal(err)
    }

    // Dump the response
    fmt.Printf("%s", body)
} 

Whilst code that you’d normally write would be more involved than this; the code above is enough to make a basic, encrypted, request, using HTTP Basic Authentication.

Passing the Credentials Securely Using Node.js

Now let’s have a look at how to use Basic Authentication using Node.js. This example, which uses Node’s HTTPS package, is only slightly longer than the Go example.

After requiring the relevant libraries, a simple object, options, is created, which contains the relevant parameters required for the connection; note the last one, auth. When the request is made, this will be Base64 encoded, and the transmission encrypted as it’s being sent over HTTPS.

var querystring = require('querystring');
var https = require('https');

var options = {
    host: 'www.callfire.com',
    path: '/api/1.1/rest/contact',
    query: '?' + querystring.stringify( { MaxResults: 5 } ),
    auth: 'YOUR_LOGIN:YOUR_SECRET'
};

var req = https.get(options, function(res) {
    res.on('data', function(d) {
        process.stdout.write(d);
    });
}).on('error', function(e) {
    console.error(e);
});

req.end();

Passing the Credentials Securely Using Curl

Likely the simplest of all the examples is Curl, which you can see below. This does the same as the previous two examples, but has the advantage of being verbose, so you can see the request and response headers, in addition to the XML response from the API endpoint.

curl -v --user YOUR_LOGIN:YOUR_SECRET https://www.callfire.com/api/1.1/rest/contact/\?MaxResults\=5

However, this example has the disadvantage of storing the password in the command history of the machine on which it’s being run. To avoid this, you can supply just the password, which causes curl to prompt for the password when the command’s run.

In Conclusion

So that’s a quick look at the authentication which the CallFire API uses to authenticate requests - HTTP Basic Authentication, and how to use it if you’re integrating using Go, Node.js or Curl.

If you would like to know more, check out the links in the Further Reading section below. It’s an interesting, and sometimes complex topic. But with a little reading, it’s reasonably easy to be understood.

Further Reading

Have more questions? Submit a request

Comments