Server Integration
For seamless backend integration, official ALTCHA libraries are available for various programming languages and environments.
Libraries
Challenge Generation
Your server must generate a fresh, single-use challenge for each user interaction. The widget requests a new challenge from the configured URL when the user begins verification.
ALTCHA Sentinel provides a built-in API endpoint, GET /v1/challenge. Custom server integrations should expose a comparable endpoint that returns a newly generated challenge on every request.
For an overview of the complete workflow, see the verification diagram.
Server Verification
After the widget verifies the user, you must cryptographically verify the ALTCHA payload submitted by the widget on your server. The payload is a Base64-encoded JSON string, typically submitted as a form field named altcha (this can be customized using the name attribute in the widget).
This verification usually occurs in your form submission handler (e.g., a POST /submit endpoint) where the form data is processed.
When using the library, verification is entirely cryptographic and requires no API calls, making it efficient and fast.
Verifying with ALTCHA Sentinel
a) Using the Library
When using the ALTCHA Sentinel server, verify the payload with the verifyServerSignature function from the ALTCHA library.
Use the API key secret generated by ALTCHA Sentinel as the HMAC key.
For supported environments, see Libraries and Plugins. Currently supported environments include TypeScript, Go, Python, Java, Elixir, PHP, Ruby, and Rust.
For an overview of the verification flow, refer to the verification diagram.
b) Using the HTTP API
For enhanced protection against replay attacks, or if a library is not available in your environment, you can use the POST /v1/verify/signature endpoint to verify the payload.
The API endpoint is public and does not require authentication.
In addition to the verified boolean, the response includes apiKey and parsed verificationData. See the API documentation for more details.
The endpoint includes built-in protection against replay attacks: it will return verified: true only once, on the first valid request.
Verifying without ALTCHA Sentinel
For solutions not using ALTCHA Sentinel, use the verification functions provided by the libraries. Each library’s documentation contains specific implementation details.
A custom server integration requires implementing an HTTP endpoint to generate new challenges. Configure this endpoint as the challenge URL in the widget.