forum
login
home HOME

KandaSearch REST API Authentication

To be able to call KandaSearch REST API, clients should provide an authentication token for each request. This token should be included as a value within an Authorization header:

--header 'Authorization: Bearer ...'

where ... should be replaced with the token value.

The request will fail in case of authentication header is not provided or provided token is already expired. In case of token is expired client need to issue a new one to continue to use KandaSearch REST API.

To obtain an authentication token client have two ways:

  • Send a request to authentication service directly
  • Call a dedicated API of KandaSearch

Both ways are legal ways to obtain an authentication token, but the first one has disadvantages. First of all, working directly with authentication service is more complex and requires to provide an additional data to succeed. Second, the service URL may change. Lastly, the service itself can be switched to use another authnetication service that has completely different API. So the first way is not much reliable in the long term. We strongly recommend to use a KandaSearch API instead to obtain tokens.

KandaSearch provides a dedicated REST API for obtaining authentication token. An API implies exchanging user credentials for the token. Note, that this API can only work with KandaSearch user credentials. That means that authentication with an external identity providers (like Google, GitLab, etc) is not supported. To get an authentication token a POST request should be executed against following URL:

curl --location 'https://api.kandasearch.com/external/v1/auth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username=...' \
--data-urlencode 'password=...'

where ... in username and password should be replaced with actual values. In a response, a string with a token value will be returned. This token value should be used for calling other KandaSearch REST API that are secured with authentication.

In case of using cURL on Windows replace all single quotes ' with double quotes " and make the command to fit one line:

curl --location "https://api.kandasearch.com/external/v1/auth/token" --header "Content-Type: application/x-www-form-urlencoded" --data-urlencode "username=..." --data-urlencode "password=..."