API authentication using an API token
Introduction
This documents details token based authentication which can be used by most Funnelback APIs.
Generating and supplying a token.
A token can 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 port>/admin-api/account/v1/login
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.
Expiry of the token.
Tokens created through the post /account/v1/login call will expire after two weeks or may expire sooner e.g. when tokens are revoked, the user changes their password or Jetty is restarted. You may need to re-create a token periodically or when the server responds with the HTTP status code 401.
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.
Non-expiring application tokens
Funnelback supports the creation of non-expiring tokens using 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.
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 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/application-token/<your applications name>
The data of the returned response is the token which should be set on the X-Security-Token header for requests.
The API allows for getting the list of Application tokens created as well as for revoking the tokens.
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.