API

This guide focuses on the API implimentation, there are platform specific instructions for WordPress and Redmine. You can also find out more about the features this product provides on the user guide.

Sentry can be integrated directly into your website and seamlessly integrates with your application. The challenges we currently use are subject to ongoing improvement. We also developing an accessible fallback option for users who cannot utilise visual challenges and exploring ways to completely remove the need to display challenges in certain cases.

Authentication

To work with Sentry, you will need to generate a public key and a secret key. These keys are bound to a specific domain and cannot be used on other domains. The public key is intended for use in a browser and is used to initiate the component within your page.

You will need to register for a free Web-Engine Cloud account to get started.

1. Once registered, log in and visit the Sentry dashboard.
2. Click Add Domain
3. Enter the domain name - note we allow for www variations of a domain automatically, if you have multiple domains, you will need separate keys for each.
4. Copy your public and secret keys - the secret key will not be shown again!

Installation

To get the challenge to appear in your page you will need to include the Sentry client script and accompanying markup. The client script is loaded from our CDN, it is required all pages you want to feature a Sentry challenge as it will look for the sentry elements and progressively enhance it with the necessary functionality.

For HTML based pages rendered on the server side, you will need to include the Sentry client script and the markup for the challenge. The markup should be placed inside a form where you want the challenge to appear.

Head section

The following code needs to be in the head of your web page, this loads the Sentry client script from our CDN and makes it available to your page.

<script src="https://sentry.we360.cloud/sentry/v1/client.js" defer></script>

Note - if you use a content security policy (CSP) you will need to allow the script to be loaded from our CDN, for example:

<meta http-equiv="Content-Security-Policy" content="script-src 'self' https://sentry.we360.cloud">

You can also load the script by injecting it into your page using JavaScript, however this is not recommended as it may not be available when the page is rendered. If you do use this method, ensure the script is loaded before the Sentry element is rendered.

const script = document.createElement('script');
script.src = "https://sentry.we360.cloud/sentry/v1/client.js";
script.defer = true;
document.head.appendChild(script);

Standard forms

For basic use with a plain HTML form, add the code to your form where you want the component to appear. Note [PUBLIC_KEY] should be replaced with the public key generated earlier. This element must be placed inside a form, it will generate an extra field in the form submission that contains the token generated by the Sentry service.

<form ...>
	...
		<div className="web-engine-sentry" data-key="[PUBLIC_KEY]"></div>
	...
</form>

Please see the confirmation of the response section below for how to handle the token generated by the Sentry service.

Single Page Applications

For javascript application such as React or Vue a different approach is needed. This part of the guide assumes knowledge of these frameworks and how to use them.

As with the example above, you must include the Sentry client script in your application, simply load the script from the CDN url shown above and ensure it is loaded before your application code runs. On page load, if the sentry script is present it will attempt to initialize itself if elements are present in the page.

If you are loading content in-place and need to trigger a Sentry element to render, this can be done by calling the "init" method of the webEngineSentry object which should be available in the global scope. In a React application this can be achieved by using useEffect within the functional component that features a Sentry placement.

typeof webEngineSentry !== "undefined"  && webEngineSentry.init();

To embed the Sentry element in your application, you can use the following code snippet. This should be placed where you want the challenge to appear, typically within a form.

<div className="web-engine-sentry" data-key="[PUBLIC_KEY]"></div>

To make sure the form submission is bound correclty and submits the verification token you will need to update the submission process.

Note - the field we will send with your form data is always called web_engine_sentry_signature, please ensure this doesn’t conflict with any other fields in your form.

The onSubmit handler should be updated as follows -

<form action='#' onSubmit='e.preventDefault(); webEngineSentry.currentTarget = e.currentTarget' noValidate>

Sentry will then handle the submission and add the token to the form data before handing it over to your script for final validation.

When the form is submitted you can then retrieve the token to send to your back end script for confirmation, or block the submission if the token is not present. This ensures that the user has successfully completed the challenge in the browser. However - it is essential to verify the token on the server side to ensure it is valid.

const form = document.querySelector('form');
form.addEventListener('submit', (e) => {
	e.preventDefault();
	const signature = webEngineSentry.getSignature();
	if (signature) {
		// proceed with form submission
		const formData = new FormData(form);
		formData.append('web_engine_sentry_signature', signature);
		// send formData to your server
	} else {
		// handle the case where the signature is not present
		alert('Please complete the Sentry challenge.');
	}
});

Confirmation

When the data from your form is submitted to your back-end and additional "web_engine_sentry_signature" field will be present containing your token. It’s essential to enforce this token with the verify call. The token might be invalid, expired, or already redeemed. Failing to verify the token will expose significant vulnerabilities in your implementation.

Note the token is valid for 5 minutes after creation and can only be verified once.

In the example below - [SECRET_KEY] is the key obtained when registering the domain. [TOKEN] is the token contained in the "web_engine_sentry_signature" field data.

This check must be ran on your server side, it cannot be done in the browser as the secret key must not be exposed to the client.

curl -X POST 'https://api.we360.cloud/api/sentry/confirm' \
     -H 'Content-Type: application/json' \
     -H 'Accept: application/json' \
     -H "Authorization: Bearer [SECRET_KEY]"  \
     -d '{ "signature": "[TOKEN]" }'

A good result will return the following, all other responses should be treated as a failure. The HTTP response code and message should indicate the issue with the request.

	{"passed":true}

There are a number of response codes that can be returned that you can use to debug your application - these include -

• 200 Good, Request passed
• 404 Not found, Unknown request, missing the required post data
• 403 Forbidden, Expired or unknown signature