API authentication using an API token
This documents details token based authentication which can be used by most Funnelback APIs. Once a token is generated, it can be set on the
X-Security-Token header to authenticate requests.
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:
By default only users with the
dxp-developer role have this permission, see user configuration files for details on how to grant that permission.
Once you have the required permission you will be able to create application tokens. The APIs for application tokens is documented on the API UI under the section
application-access-tokens. An application token can be created with the call:
PUT /application-tokens/v1/clients/<your client id>/application-token/<your applications name>
The API allows for getting the list of application tokens created as well as for revoking the tokens.
When new client application token is created it doesn’t have any implied permissions.
In the SXC client applications tokens should include the following roles:
client~primaryif the token should provide access to all search packages and data sources associated with the client.
dxp~developerif 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.|
If you are creating a token to provide an integration with the Push API to maintain content within a push data source grant
sec.continuous.restand either specify the push collections (or grant the
client~primaryrole to allow access to all the client’s search packages and data sources).
If you are creating a token to setup a higher education package solution grant both the
dxp~developerroles as the setup process requires mostly the same level of permission as the user creating the token.
|This feature should not be used in the Squiz Experience Cloud, please use client application tokens instead.|
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 deleted if the associated user is deleted
The permission required is the same as for client application tokens:
An application token can be created with the call:
PUT /application-tokens/v1/application-token/<your applications name>
Further documentation is available on the API UI under the section
A token can also be created through the API UI using the following call shown under user-account-management.
The full URL of the call would be:
The username and password should be passed in as
POST form parameters, for example in curl this would look like:
curl -v 'https://<server>:<port>/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.
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 Experience Cloud 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.
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.