Skip to content
ALTCHA ALTCHA ALTCHA

PoW Challenges API

Utilize the Challenge API in conjunction with the ALTCHA Widget to generate and validate cryptographic challenges.

The API offers several advantages over self-hosted challenge verification:

  • Simplified integration with any backend or CMS.
  • Additional security measures such as challenge expiration and reuse protection.
  • Ability to utilize the Spam Filter directly from the widget, allowing data classification before submission to your server.
  • Zero API requests made from your server; everything is cryptographically verified, reducing latency and eliminating potential network issues.

Authorization

Accessing the API requires an API Key. Refer to API authorization.

Using with the Widget

To employ the API with ALTCHA’s widget, configure the challengeurl and remember to include your API Key in the URL:

<altcha-widget
  challengeurl="https://eu.altcha.org/api/v1/challenge?apiKey=ckey_..."
></altcha-widget>

Enable Spam Filter

The API also allows for automatic data classification for spam using the Spam Filter. To enable the Spam Filter, add the spamfilter attribute to the widget (requires version 0.3+):

<altcha-widget
  challengeurl="https://eu.altcha.org/api/v1/challenge?apiKey=ckey_..."
  spamfilter
></altcha-widget>

With Spam Filter enabled, verification will automatically submit textual fields from the form along with detected email addresses and return a classification result.

To process the classification on your website, utilize the serververification event of the widget. A limited version of the classification is also included in the new payload submitted to your server.

Server Verification

When using ALTCHA’s API with spamfilter, the payload received on your server has a different format than the payload generated by the widget.

You will receive a base64-encoded string containing a JSON-encoded object:

{
  "algorithm": "SHA-256",
  "signature": "71b86949a1a84595f71d8abd7bdef414e8b883247e30cba93f4946b028c4fbf1",
  "verificationData": "classification=BAD&score=7.75&...&time=1713566250&verified=true",
  "verified": true
}

Payload properties:

  • algorithm - The algorithm used for HMAC signature.
  • signature HMAC signature of the verificationData.
  • verificationData - URL-encoded verification and classification data.
    • time - Timestamp of the verification in seconds.
    • verified - Whether the solution has been successfully verified.
    • With spamfilter enabled (see Spam Filter response):
      • classification - Spam Filter classification.
      • email - Submitted email.
      • expire - Expiration time in seconds.
      • fields - Array of field names that were submitted.
      • fieldsHash - SHA hash of the field values.
      • ipAddress - The user’s IP address.
      • reasons - Array of reasons.
      • score - Overall classification score.
  • verified - Whether the solution has been successfully verified.

Verifying the Signature

To verify that the client has been verified, check the signature received in the payload:

  1. Calculate a SHA hash of the verificationData (using the algorithm).
  2. Calculate an HMAC signature with the same algorithm, where the hmac_key is the secret part of your API Key (i.e., csec_...).

Example pseudo-code using the SHA-256 algorithm:

// calculate SHA hash of the `verificationData`, unparsed, as they appear in the payload (hash contains raw binary data, NOT hex-encoded):
hash = sha2(payload.verificationData);


// calculate HMAC signature
signature = hmac_sha2_hex(hash, hmac_key);

The payload is considered verified if the calculated signature matches the signature property from the payload. It’s advisable to also verify the submitted data, as outlined in the section Verifying Fields below.

Alternatively, if you cannot verify the signature cryptographically, utilize the Server Signature verification endpoint.

Verifying Fields

If you utilize the Spam Filter, the verificationData will include additional properties: fields and fieldsHash. These properties enable you to validate the accuracy of the classified data. This verification step ensures that the user has not altered the submitted data since its validation by the Spam Filter.

To verify the fields hash, concatenate the values of the fields with \n (new line) and compute the SHA hash (using the specified algorithm). For example, if fields = field1,field2,field3:

hash = sha2_hex(field1_value + "\n" + field2_value + "\n" + field3_value);

Ensure that the values are sorted in the order they appear in the fields property.

The data is deemed correct if the computed hash matches the fieldsHash.

API Endpoints

If you prefer to use the API directly, without the widget, utilize the following endpoints. Remember that the Referer header must always be present and must contain the origin (domain) of your website.

Creating a New Challenge

Verifying Solution

Validating Server Signature

This endpoint serves as an alternative way of verifying the server signature received from /api/v1/challenge/verify. Cryptographic verification is recommended.