Zum Inhalt springen
ALTCHA ALTCHA ALTCHA

Dieser Inhalt ist noch nicht in deiner Sprache verfügbar.

Server Integration

For seamless backend integration, we provide official ALTCHA libraries for various programming languages and environments.

We recommend using ALTCHA Sentinel for verification as it offers robust protection and enhanced security.

Libraries

TypeScript
PHP
Go
Python
Java
Ruby
Elixir
Community libraries: C# Clojure Rust

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., POST /submit endpoint) where the form data is processed.

The verification is entirely cryptographic, requiring no API calls, making it extremely efficient and fast.

Verifying with Sentinel

a) Using the Library

When using the Sentinel server, verify the payload using the verifyServerSignature function from the Altcha library. Use the API key secret generated by Sentinel as the HMAC key.

For an overview of the verification flow, refer to the verification diagram.

For supported environments, see Libraries and Plugins. Currently supported environments include TypeScript, Go, Python, Java, Elixir, PHP, and Ruby.

verify.js
import { verifyServerSignature } from 'altcha-lib';


// Use the secret from your Sentinel App for the API key used in the challenge
const apiKeySecret = 'sec_...';


// The Base64-encoded payload received from the Widget upon submission
const payload = '...';


// Verify the payload
const { verificationData, verified } = await verifyServerSignature(payload, apiKeySecret);


if (verified) {
  // Verification successful - process the submission
}

This pattern is consistent across all supported languages. Check the documentation for your specific library for implementation details.

b) Using the HTTP API

If the library is not available in your environment, you can use the POST /v1/verify/signature endpoint to verify the payload:

verify-api.js
// Send HTTP request with the received payload
const resp = await fetch('https://sentinel.example.com/v1/verify/signature', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    payload,
  }),
});


// Read the JSON response
const { verified } = await resp.json();


if (verified) {
  // Verification successful – process the submission
}

The API endpoint is public and does not require authentication. In addition to the verified boolean, the response also includes apiKey and parsed verificationData. See the API documentation for more details.

Verifying without Sentinel

For solutions not using the Sentinel server, utilize the verification functions provided by our libraries. Each library’s documentation contains specific implementation details.

A custom server integration requires implementing a HTTP endpoint to generate new challenges. Configure this endpoint’s address as challengeurl in the widget.

server.js
import { createChallenge } from 'altcha-lib';


const hmacKey = '$ecret.key'; // Replace with your secret HMAC key


// Generate and return a new challenge as JSON
const challenge = await createChallenge({
  hmacKey,
});

For submission verification, use the verifySolution function:

server.js
import { verifySolution } from 'altcha-lib';


const hmacKey = '$ecret.key'; // Replace with your secret HMAC key


// Verify the submitted payload
const verified = await verifySolution(payload, hmacKey);


if (verified) {
  // Verification successful - process the submission
}

Examples

Example server implementations: