Help Center

Menu

API authentication using an API token

This document details token based authentication which can be used by most Funnelback APIs. Once a token is generated, it can be used to authenticate Funnelback API requests.

Non-expiring client application tokens

Funnelback supports the creation of non-expiring tokens using client application tokens. This is useful when you want an application to be able to interact with Funnelback without giving the application your password. It also provides a mechanism for revoking tokens of individual applications. This method is recommended over user application tokens, and has the following advantages:

  • permissions associated with application tokens are configurable

  • application tokens for a client may be administered by multiple users

  • application tokens can be cloned (useful when creating new tokens, or configuring automated secrets rotation)

  • application tokens will not be deleted if the user that created them is deleted

To be able to create these tokens you will need the permission:

sec.application-token.non-expiring.create=yes

By default, only users with the default-super-user or dxp-developer role have this permission.

Once you have the required permission you will be able to create application tokens.

Client application tokens can be created via the search dashboard or an API call.

Create a client application token using the search dashboard

  1. Log in to the search dashboard and select create a new application token from the users and roles section of the dashboard menu.

  2. Select a client from the client dropdown. The token that is created will be added to this client.

  3. Enter a name for the token.

  4. Click the create application token button. The generated token details are displayed in a box at the top of your screen.

    api token result

  5. Record the token details somewhere safe (e.g. in you password vault) as you can’t retrieve these details later. In the DXP you will need the token’s username and password values to interact with the API due to how the DXP authentication works.

  6. Select the permissions that are assigned to this token. The permissions assigned dictate what can be done when using the token to access Funnelback’s APIs.

Permissions required for common scenarios:

  • Push API integration:

    • Permissions: sec.continuous.rest.

    • Manage roles: Set this to your primary role.

    • Collections: Select the push data sources that this token should have access to.

      Permissions and collections are specified here so that the token access is locked down.

Create a client application token using the API

The APIs for application tokens are documented in the API UI under the section application-access-tokens. An application token can be created with the call:

PUT /application-tokens/v2/clients/<your client id>/application-token/<your application name>

which returns something like

{
  "data": {
    "token": "exampleUserTokenString", (1)
    "tokenAsHTTPBasicAuth": {
      "password": "exampleUserTokenHTTPPassword", (2)
      "username": "exampleUserTokenHTTPUsername" (3)
    }
  },
  "errorMessage": "string"
}
1 The token value can be passed in the X-Security-Token HTTP header to authenticate API requests.
2 The tokenAsHTTPBasicAuth password can be used to authenticate with the API using HTTP basic authentication.
3 The tokenAsHTTPBasicAuth username can be used to authenticate with the API using HTTP basic authentication.

The API also includes calls for getting the list of application tokens created as well as for revoking the tokens.

Permissions need to be assigned to the token after creation. This can be done via the search dashboard by selecting manage application tokens from the users and roles section of the dashboard menu, then selecting the token from the list that is presented.

Client tokens should not be used for manually managing Funnelback configuration using a WebDAV client; instead, it is recommended you use the Non-expiring user application tokens below so that they can be tied back to your user.

Creating a client application token for use with the Squiz DXP

When a new client application token is created it doesn’t have any implied permissions.

In the Squiz DXP, client applications tokens should include the following roles:

  • client~primary if the token should provide access to all search packages and data sources associated with the client.

  • dxp~developer if the token should provide the same level of access as their administration user has.

Manually setting the permissions granted to a token allows you to precisely control the functions granted to the token.

Managing client application tokens

The application token management screen is accessed by selecting manage application tokens from the users and roles section of the dashboard menu.

The application management screen allows you to:

  • Revoke client applications tokens

  • Clone a client application token, creating a new token that has the same permissions as the token you are cloning.

Non-expiring user application tokens

This feature should be used for API interactions where the action is tied back to the user. For applications, it is generally better to use a client token as this is not tied to a user account and won’t get deleted when a user account is removed. These user API tokens should be used when managing Funnelback configuration using a WebDAV client.

Non-expiring tokens can also be created on a per-user basis. Note that these tokens:

  • share the permissions of the user that created them.

  • are only visible to the creating user.

  • will be removed if the associated user is deleted.

The permission required is the same as for client application tokens:

sec.application-token.non-expiring.create=yes
User tokens can only be created by calling the API

An application token can be created with the call:

PUT /application-tokens/v2/application-token/<your applications name>

which returns something like

{
  "data": {
    "token": "exampleUserTokenString", (1)
    "tokenAsHTTPBasicAuth": {
      "password": "exampleUserTokenHTTPPassword", (2)
      "username": "exampleUserTokenHTTPUsername" (3)
    }
  },
  "errorMessage": "string"
}
1 The token value can be passed in the X-Security-Token HTTP header to authenticate API requests.
2 The tokenAsHTTPBasicAuth password can be used to authenticate with the API using HTTP basic authentication.
3 The tokenAsHTTPBasicAuth username can be used to authenticate with the API using HTTP basic authentication.

Further documentation is available on the API UI under the section application-access-tokens.

Permissions required for common scenarios:

  • WebDAV access, or higher education stencil setup:

    • Manage roles: Set this to your primary and resources roles + dxp~developer.

      Permissions and collections are inherited from the applied roles.

Login tokens

Login tokens can only be created by calling the API

A token can also be created through the API UI using the following call shown under user-account-management.

POST /account/v1/login

The full URL of the call would be:

https://<server>/admin-api/account/v1/login

where:

  • <server> is the Funnelback administration server hostname.

The username and password should be passed in as POST form parameters, for example in curl this would look like:

curl -v 'https://<server>/admin-api/account/v1/login?remember-me=true' -H 'Content-Type: application/x-www-form-urlencoded' --data 'username=<username>&password=<password>'

The token will be returned in the response’s X-Security-Token header. To use this token add the token to the value to the X-Security-Token header on each request.

Expiry of the token.

Tokens created through the post /account/v1/login API call can expire for a number of reasons, including:

  • being older than the server is configured to permit (1 hour for the Squiz DXP and hosted versions of Funnelback or 4 days if the default expiry has not been changed).

  • on manual revocation.

  • when a user’s password is changed.

  • when Funnelback is restarted.

A HTTP 401 error code will be returned when attempting to authenticate with an expired token. A new token can be created via the login API in order to continue accessing Funnelback’s API.

Basic authentication compared to tokens.

Although some Funnelback APIs will allow basic authentication, it is best to use a token especially if a high number of requests are going to be made.

Lost tokens

If you have created an application token and later lost the token, it is impossible to re-generate that token and a new token must be created.

See also