API authentication methods

Managed by | Updated .

Funnelback provides various APIs that can be used for integration purposes:

  • Push API: Push content to Funnelback via Push collections
  • Admin API: Interact with the administrative features of Funnelback. This API is used by the Marketing Dashboard and the Administration Interface
  • Public API: Perform search and get results as HTML, JSON or XML

Documentation for the Push & Admin APIs can be found on the API-UI interface.

These different APIs have different authentication methods:

  • Basic HTTP authentication is supported on the Push API and Public API. This method allows you to make API requests containing an Authorization header embedding the credentials, without having to login first.
  • Token-based authentication is supported on all API endpoints. It's also the only authentication method supported for the Admin API.

Basic HTTP Authentication

Basic HTTP  authentication is the simplest option which involves sending the username and password combination as an encoded value for every request. It does not require any sessions, cookies or login page for it to work and has no expiry.

Note: Basic HTTP Authentication works with the Push API and Public API. It is currently not supported with the Admin API.

Below is an example on how to derive the authorization header which can be used to access the Push API and Public API.

  1. Combine the username and password separating them with a single colon (:)
  2. Encode the resulting string using base64. For testing purposes and non-production accounts, you can with https://www.base64decode.org/)
  3. Enter the following into the headers of each API request: Authorization:Basic <encoded string>

The following is a an example of using Basic HTTP authentication with the Push API:

Username: admin
Password: pwd
Collection name: example-push
Push API enpoint: https://127.0.0.1:8443/push-api/v1/collections/example-push/state
$printf admin:pwd | base64
YWRtaW46cHdk

$curl -k -X GET --header "Authorization: Basic YWRtaW46cHdk"  "https://127.0.0.1:8443/push-api/v1/collections/example-push/state"
{
  "state" : "STOPPED"
}

Token-based Authentication

With token-based authentication a login API call to retrieve an authentication token must be performed first. This call will return an authentication token in the form of a HTTP header and cookie that needs to be passed to subsequent requests.

Below is an example of making the login API call via cURL on the command line, showing the response headers and the response content:

$ curl -ki -X POST -d "username=admin&password=admin" https://localhost:8443/admin-api/account/v1/login

HTTP/1.1 200 OK
Date: Wed, 18 Jan 2017 18:02:05 GMT
X-Security-Token: YWRtaW46MTQ4NTk3MjEyNTY5NDplNGJiOTA3MTVmOTYxNWY3ZDI5MDYyZDM4MDI2OThkZDg4ZTU4OWYzM2I3MjhiMWY0ZjU4MGIzNTcwZjBmOWQ5
Set-Cookie: SPRING_SECURITY_REMEMBER_ME_COOKIE=YWRtaW46MTQ4NTk3MjEyNTY5NDplNGJiOTA3MTVmOTYxNWY3ZDI5MDYyZDM4MDI2OThkZDg4ZTU4OWYzM2I3MjhiMWY0ZjU4MGIzNTcwZjBmOWQ5;Path=/;Expires=Wed, 01-Feb-2017 18:02:05 GMT;Secure;HttpOnly
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Content-Type: application/json; charset=UTF-8
Pragma: no-cache
Cache-Control: no-cache, no-store, max-age=0
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Transfer-Encoding: chunked
Server: Jetty(9.2.z-SNAPSHOT)

{
  "errorMessage" : null,
  "data" : "Authenticated, see x-security-token."
}

Two response headers are of interest:

  • X-Security-Token contains the authentication token as-is. It can be used to extract the token for later use.
  • Set-Cookie: SPRING_SECURITY_REMEMBER_ME_COOKIE contains the token in the form of a cookie. This is a convenience method when interacting with the API from a browser (Ajax requests). The browser will automatically send that cookie to subsequent calls to the API without having to specify custom headers.

Subsequent calls to the API must pass the token, either in the form of a custom header:

$ curl -k -H 'X-Security-Token: YWRtaW46MTQ4NTk3MjEyNTY5NDplNGJiOTA3MTVmOTYxNWY3ZDI5MDYyZDM4MDI2OThkZDg4ZTU4OWYzM2I3MjhiMWY0ZjU4MGIzNTcwZjBmOWQ' https://localhost:8443/admin-api/account/v1/

{
  "errorMessage" : null,
  "data" : {
    "id" : "admin",
    "fullName" : "Sample Super User",
    ...
  }
}

Or in the form of a cookie:

$ curl -k -b 'SPRING_SECURITY_REMEMBER_ME_COOKIE=YWRtaW46MTQ4NTk3MjEyNTY5NDplNGJiOTA3MTVmOTYxNWY3ZDI5MDYyZDM4MDI2OThkZDg4ZTU4OWYzM2I3MjhiMWY0ZjU4MGIzNTcwZjBmOWQ5' https://localhost:8443/admin-api/account/v1/

{
  "errorMessage" : null,
  "data" : {
    "id" : "admin",
    "fullName" : "Sample Super User",
    ...
  }
}

Token expiration and caveats

A token generated via the login API call will expire after 2 weeks. This is not configurable at the moment.

Please note that the token is derived from the user password hash. While it cannot be used to retrieve the original user password, it needs to be transmitted over secure channels only (HTTPS). If the token is intercepted an attacker could impersonate the user via the API with the same level of privileges.

Because of these two reasons, it is not recommended to store a token and use it as a permanent API token for integration purposes. A client wanting to integrate with the Funnelback API either can use Basic HTTP authentication when available, or obtain a token via the login API call first. Creating a dedicated user with limited privileges is also recommended.

Additional Resources

Was this artcle helpful?

Comments