HTTP API

The api provides a few endpoints via https://api.alancaptcha.com.

• /challenge to retrieve a new challenge
• /challenge/validate to validate if the solutions are correct
• /credentials/validate to validate if the credentials (ApiKey, SiteKey) are correct
• /health to check weather the api functions correctly at the time

/challenge

This endpoint is used to retrieve challenges from the browser of the user.

Send a GET or POST request to https://api.alancaptcha.com/challenge with a valid SiteKey to obtain a challenge.

In case of GET, the parameters can be usual GET parameters. In case of POST you can send a json document or form data encoded.

Parameter	Required	Description
siteKey	mandatory	The SiteKey you received from registering your site.
monitorTag	optional	A previously created monitorTag identifying your form.
numberOfChallenges	optional	Integer between 1 and 1000. If greater than 1, returns a json array with given number of challenge JWT's
numberOfPuzzles	optional	Integer. If allowed, generates a challenge with this number of puzzles. The default configuration can always be increased.
difficulty	optional	Integer. If allowed, set the difficulty for generated puzzles. The default configuration can always be increased.
rounds	optional	Integer. If allowed, set the number of rounds to compute a hash needed for a solution. The default configuration can always be increased.

This endpoint returns a json document of the form:

{
  "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJjYXB0Y2hhIiwiZXhwIjoxNjgzMjc5OTAzLCJuYmYiOjE2ODMyNzk2MDMsImlhdCI6MTY4MzI3OTYwMywianRpIjoiYWQ5ODc5ZDc2YjUyMmRlYTY4ZTcwZDgzY2UxZDkwMGRhMDc4MDVlZiIsIm9yaWdpbiI6IiIsIm1vbml0b3JUYWciOiJnZW5lcmFsIiwiY2hhbGxlbmdlIjp7ImlkIjoiOVhNa2djVFJlQzBYYWpZbXRtSUhEbDZlQkM1UG1XIiwicHV6emxlcyI6W3siaWQiOiIzWTBheTFuMHpSWmFUeVlvWGpnOEVBNjU5TUEwbVYiLCJ0eXBlIjoic2hhMjU2IiwicmFuZCI6IkJPVWNWZGxxTVZHRE44N3QwSlZIbzRNVzJyUUM0YlBycUJrR1d3TVUiLCJkaWZmaWN1bHR5IjoxfSx7ImlkIjoiWTVjTmdJeXZPRDdITUNpSnJZYmlTckE2b3lYc0oyIiwidHlwZSI6InNoYTI1NiIsInJhbmQiOiJWd2tuVjZyZEFxbmNlZzZSYnpURE4yWWE1MlBENXZFWXl3R3laZ1FvIiwiZGlmZmljdWx0eSI6MX0seyJpZCI6IjMwOTIyZnRNUmhHbGRZckFsZWtSRU5tN0lNeXBtQSIsInR5cGUiOiJzaGEyNTYiLCJyYW5kIjoiTG1kRlZIVFF6c2k5Z3diQk5hMDJ5YUJVb3dlNDFpR2Rxd2hOOThTOCIsImRpZmZpY3VsdHkiOjF9LHsiaWQiOiJzcFJtVDBiMWRxWnNDVnVaZTNmWTdOQVJZcmNWVFQiLCJ0eXBlIjoic2hhMjU2IiwicmFuZCI6Ik9CRGh3WWs0NDhJcWZXanNUNjg0OTJwem5CeHV5YXF3Z2N0bHJYWG8iLCJkaWZmaWN1bHR5IjoxfSx7ImlkIjoid2pyUjY5VUJPdmdvN1dVR2pNdzVQcUJtWDlQaEs1IiwidHlwZSI6InNoYTI1NiIsInJhbmQiOiIwbE52ZmFXZ1RnbWtEOXVXWDFJMW0zZHk1Y2ZEa3l5ZVB4Q0pMdzRjIiwiZGlmZmljdWx0eSI6MX1dfSwic2l0ZUtleSI6ImEzNTIzYjI1LWI5NWUtNDEzNC05MmFiLWRjYzcwNGRhYWQ5ZCJ9.gFVJlvByKWWVekjz0LxY6wHufIX1Hw068yaH0A2AoJk"
}

or if 1 < numberOfChallenges

[
  "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJjYXB0Y2hhIiwiZXhwIjoxNjgzMjc5OTAzLCJuYmYiOjE2ODMyNzk2MDMsImlhdCI6MTY4MzI3OTYwMywianRpIjoiYWQ5ODc5ZDc2YjUyMmRlYTY4ZTcwZDgzY2UxZDkwMGRhMDc4MDVlZiIsIm9yaWdpbiI6IiIsIm1vbml0b3JUYWciOiJnZW5lcmFsIiwiY2hhbGxlbmdlIjp7ImlkIjoiOVhNa2djVFJlQzBYYWpZbXRtSUhEbDZlQkM1UG1XIiwicHV6emxlcyI6W3siaWQiOiIzWTBheTFuMHpSWmFUeVlvWGpnOEVBNjU5TUEwbVYiLCJ0eXBlIjoic2hhMjU2IiwicmFuZCI6IkJPVWNWZGxxTVZHRE44N3QwSlZIbzRNVzJyUUM0YlBycUJrR1d3TVUiLCJkaWZmaWN1bHR5IjoxfSx7ImlkIjoiWTVjTmdJeXZPRDdITUNpSnJZYmlTckE2b3lYc0oyIiwidHlwZSI6InNoYTI1NiIsInJhbmQiOiJWd2tuVjZyZEFxbmNlZzZSYnpURE4yWWE1MlBENXZFWXl3R3laZ1FvIiwiZGlmZmljdWx0eSI6MX0seyJpZCI6IjMwOTIyZnRNUmhHbGRZckFsZWtSRU5tN0lNeXBtQSIsInR5cGUiOiJzaGEyNTYiLCJyYW5kIjoiTG1kRlZIVFF6c2k5Z3diQk5hMDJ5YUJVb3dlNDFpR2Rxd2hOOThTOCIsImRpZmZpY3VsdHkiOjF9LHsiaWQiOiJzcFJtVDBiMWRxWnNDVnVaZTNmWTdOQVJZcmNWVFQiLCJ0eXBlIjoic2hhMjU2IiwicmFuZCI6Ik9CRGh3WWs0NDhJcWZXanNUNjg0OTJwem5CeHV5YXF3Z2N0bHJYWG8iLCJkaWZmaWN1bHR5IjoxfSx7ImlkIjoid2pyUjY5VUJPdmdvN1dVR2pNdzVQcUJtWDlQaEs1IiwidHlwZSI6InNoYTI1NiIsInJhbmQiOiIwbE52ZmFXZ1RnbWtEOXVXWDFJMW0zZHk1Y2ZEa3l5ZVB4Q0pMdzRjIiwiZGlmZmljdWx0eSI6MX1dfSwic2l0ZUtleSI6ImEzNTIzYjI1LWI5NWUtNDEzNC05MmFiLWRjYzcwNGRhYWQ5ZCJ9.gFVJlvByKWWVekjz0LxY6wHufIX1Hw068yaH0A2AoJk",
  "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJjYXB0Y2hhIiwiZXhwIjoxNzIwNjAyMTc1LCJuYmYiOjE3MjA2MDE4NzUsImlhdCI6MTcyMDYwMTg3NSwianRpIjoiNGMzNmQ1ZjQ5YmE0YmM0OTE2ZGY2MDhiNzE3YWE3MTBiNmNhYWQ5OCIsIm9yaWdpbiI6Imh0dHA6Ly8xMjcuMC4wLjE6ODEyMyIsIm1vbml0b3JUYWciOiIiLCJjaGFsbGVuZ2UiOnsiaWQiOiI2MWU5YTM1MzY3MDFkNTYyYjJlYjE1YTJiYmQyMjQiLCJ2ZXJzaW9uIjoyLCJwdXp6bGVzIjpbeyJpZCI6Ijg1YTc3NmY3M2MxNjRjMTUxZGIzYTJmYjdhN2M2MiIsInQiOiJzaGEyNTYiLCJyYW5kIjoiNTU5NzQ4ZjgiLCJkaWZmaWN1bHR5Ijo3LCJoYiI6IjIxMDc2NjhlNGQxMzU1OTc0OGY4IiwiciI6MX0seyJpZCI6ImMyNTVkYTdiMjA5YmFiMjNkNGFiNmI4Njk4OWI3MyIsInQiOiJzaGEyNTYiLCJyYW5kIjoiMzhmZWM2NWMiLCJkaWZmaWN1bHR5Ijo3LCJoYiI6IjIxMDc2NjhlNGQxMzM4ZmVjNjVjIiwiciI6MX0seyJpZCI6IjFmODk1NDdiZmQ2MWJlNDg1YTZhMDQzZWQ4NDJkNyIsInQiOiJzaGEyNTYiLCJyYW5kIjoiOWFjZTE5YzciLCJkaWZmaWN1bHR5Ijo3LCJoYiI6IjIxMDc2NjhlNGQxMzlhY2UxOWM3IiwiciI6MX0seyJpZCI6ImNkYmVkOGZlMzE4OWQxNzIyNjJkMDkxODNkNGQzNCIsInQiOiJzaGEyNTYiLCJyYW5kIjoiY2JhZGQ3NmIiLCJkaWZmaWN1bHR5Ijo3LCJoYiI6IjIxMDc2NjhlNGQxM2NiYWRkNzZiIiwiciI6MX0seyJpZCI6IjMxYzE0MjYyODMxODY5YWRlMWNlYWYwYjZhMTI0NyIsInQiOiJzaGEyNTYiLCJyYW5kIjoiNDk3NGUzM2EiLCJkaWZmaWN1bHR5Ijo3LCJoYiI6IjIxMDc2NjhlNGQxMzQ5NzRlMzNhIiwiciI6MX1dfSwic2l0ZUtleSI6Imx4ekdzaWE4UGxNQXJpSVczdG03VjZpQUVBdW5PWlFPYmhSalE2Q2YifQ.qNTEloEQey3lEjZFSv096RoeldunbLwuUq4wW1aI-bE"
]

The JWT (Json Web Token) cryptographically encodes the challenge that needs to be solved.

/challenge/validate

This endpoint is used to validate a solved challenge.

Send a POST request to https://api.alancatpcha.com/challenge/validate using a private ApiKey you previously created.

You need to provide the following parameters either as a JSON document or form data encoded:

Parameter	Required	Description
key	mandatory	Your ApiKey.
jwt	mandatory	The JWT received from the /challenge endpoint.
puzzleSolutions	mandatory	An array of puzzle solutions.

An example request might look like this

{
  "key": "YOUR-SECRET-API-KEY",
  "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJjYXB0Y2hhIiwiZXhwIjoxNjgzMjc5OTAzLCJuYmYiOjE2ODMyNzk2MDMsImlhdCI6MTY4MzI3OTYwMywianRpIjoiYWQ5ODc5ZDc2YjUyMmRlYTY4ZTcwZDgzY2UxZDkwMGRhMDc4MDVlZiIsIm9yaWdpbiI6IiIsIm1vbml0b3JUYWciOiJnZW5lcmFsIiwiY2hhbGxlbmdlIjp7ImlkIjoiOVhNa2djVFJlQzBYYWpZbXRtSUhEbDZlQkM1UG1XIiwicHV6emxlcyI6W3siaWQiOiIzWTBheTFuMHpSWmFUeVlvWGpnOEVBNjU5TUEwbVYiLCJ0eXBlIjoic2hhMjU2IiwicmFuZCI6IkJPVWNWZGxxTVZHRE44N3QwSlZIbzRNVzJyUUM0YlBycUJrR1d3TVUiLCJkaWZmaWN1bHR5IjoxfSx7ImlkIjoiWTVjTmdJeXZPRDdITUNpSnJZYmlTckE2b3lYc0oyIiwidHlwZSI6InNoYTI1NiIsInJhbmQiOiJWd2tuVjZyZEFxbmNlZzZSYnpURE4yWWE1MlBENXZFWXl3R3laZ1FvIiwiZGlmZmljdWx0eSI6MX0seyJpZCI6IjMwOTIyZnRNUmhHbGRZckFsZWtSRU5tN0lNeXBtQSIsInR5cGUiOiJzaGEyNTYiLCJyYW5kIjoiTG1kRlZIVFF6c2k5Z3diQk5hMDJ5YUJVb3dlNDFpR2Rxd2hOOThTOCIsImRpZmZpY3VsdHkiOjF9LHsiaWQiOiJzcFJtVDBiMWRxWnNDVnVaZTNmWTdOQVJZcmNWVFQiLCJ0eXBlIjoic2hhMjU2IiwicmFuZCI6Ik9CRGh3WWs0NDhJcWZXanNUNjg0OTJwem5CeHV5YXF3Z2N0bHJYWG8iLCJkaWZmaWN1bHR5IjoxfSx7ImlkIjoid2pyUjY5VUJPdmdvN1dVR2pNdzVQcUJtWDlQaEs1IiwidHlwZSI6InNoYTI1NiIsInJhbmQiOiIwbE52ZmFXZ1RnbWtEOXVXWDFJMW0zZHk1Y2ZEa3l5ZVB4Q0pMdzRjIiwiZGlmZmljdWx0eSI6MX1dfSwic2l0ZUtleSI6ImEzNTIzYjI1LWI5NWUtNDEzNC05MmFiLWRjYzcwNGRhYWQ5ZCJ9.gFVJlvByKWWVekjz0LxY6wHufIX1Hw068yaH0A2AoJk",
  "puzzleSolutions": [
    {
      "id": "3Y0ay1n0zRZaTyYoXjg8EA659MA0mV",
      "solution": 17
    },
    {
      "id": "Y5cNgIyvOD7HMCiJrYbiSrA6oyXsJ2",
      "solution": 49
    },
    {
      "id": "30922ftMRhGldYrAlekRENm7IMypmA",
      "solution": 3
    },
    {
      "id": "spRmT0b1dqZsCVuZe3fY7NARYrcVTT",
      "solution": 33
    },
    {
      "id": "wjrR69UBOvgo7WUGjMw5PqBmX9PhK5",
      "solution": 1
    }
  ]
}

/credentials/validate

This endpoint is used to validate given credentials (ApiKey, SiteKey). e.g. to check if a SiteKey exists and matches the given ApiKey.

Send a GET or POST request to https://api.alancaptcha.com/credentials/validate.

In case of GET, the parameters can be usual GET parameters. In case of POST you can send a json document or form data encoded.

Parameter	Required	Description
siteKey	mandatory	The SiteKey
key	mandatory	The ApiKey

This endpoint returns a json document of the form:

{
  "success": true,
  "code": "1722245251631"
}

/health

This endpoint can be used to check, weather the api functions correctly at the time.

Send a GET request to https://api.alancaptcha.com/health.

An example response looks like this:

{
  "success": true,
  "message": "Everything up and running",
  "context": "production",
  "selfCheckResult": "success",
  "selfCheckTime": 0.001870870590209961
}