<script>
	import Libraries from '$components/blocks/Libraries.svelte';
</script>

# Server Integration

For seamless backend integration, official ALTCHA [libraries](/docs/integration/server/#libraries) are available for various programming languages and environments.

## Libraries

<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](/docs/sentinel/) provides a built-in API endpoint, [`GET /v1/challenge`](/sentinel-api-docs-v1.html#tag/challenge/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](/docs/integration/diagrams/).

## 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 <ins>with ALTCHA Sentinel</ins>

#### a) Using the Library

When using the [ALTCHA Sentinel](/docs/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](/docs/integration/server/#libraries). Currently supported environments include **TypeScript, Dart, Go, Python, Java, Elixir, PHP, Ruby, Rust, and C++**.

For an overview of the verification flow, refer to the [verification diagram](/docs/integration/diagrams/#1-sentinel-verification).

#### b) Using the HTTP API

For enhanced protection against [replay attacks](/docs/integration/security-recommendations/#replay-attacks-with-server-signatures), or if a library is not available in your environment, you can use the [`POST /v1/verify/signature`](/sentinel-api-docs-v1.html#tag/verify/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](/sentinel-api-docs-v1.html#tag/verify/post/v1/verify/signature) 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 <ins>without</ins> ALTCHA Sentinel

For solutions **not using ALTCHA Sentinel**, use the verification functions provided by the [libraries](/docs/integration/server/#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.

## Related Documentation

* [Server Verification Diagrams](/docs/integration/diagrams/)
* [Security Recommendations](/docs/integration/security-recommendations/)
* [Troubleshooting](/docs/integration/troubleshooting/)