Help Center

Menu

API authentication methods

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

  • Push API: Push content to Funnelback via push data source

  • Admin API: Interact with the administrative features of Funnelback. This API is used by the search and insights dashboards.

  • Public API: Perform search and get results as HTML, JSON or XML

Documentation for the push and admin APIs can be found on the API-UI interface.

These different APIs support the following authentication methods:

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:

  • 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 1 hour. This is not configurable.

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.

Basic HTTP authentication

Basic HTTP authentication is the simplest option which involves sending a 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 via an administration user works with the push API and public API. The admin API supports basic HTTP authentication, but only when using a client or user authentication token.

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 an example of using basic HTTP authentication with the push API and the following attributes:

  • 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"
}

The admin API supports basic HTTP authentication using an authentication token.

When the token is generated, the API returns a username and password that can be used to access the admin API.

v1 API tokens did not support basic HTTP authentication and must be regenerated.

Additional resources