Step 1: Enable your Project for Device Fingerprinting
Reach out to Stytch to be enabled for Device Fingerprinting. Device Fingerprinting is still in an open beta, to take part in the beta, just reach out to us and we can enable you for this new product.
Step 2: Add Device Fingerprinting to your app
You only need to add a simple script tag to the HEAD or BODY of your app.
<HEAD>
<script src=https://elements.stytch.com/telemetry.js></script>
</HEAD>
Once that is live in your app, you'll be collecting Stytch Device Fingerprinting data automatically, no other work necessary.
Step 3: In-house decisioning, or base it on Stytch?
Our Device Fingerprinting product can be used in two ways:
Collection only
In this mode, Device Fingerprinting will collect information about devices using your app and you'll use our Lookup endpoint to receive all of that data directly. This lets you make the rules, decisions, and generate insights based on the raw data from Stytch.
If you'd like to build your own insights on the raw data, skip directly to step 5.
Collection and decisioning
In this mode, Stytch will collect the data, but we'll also return a score based on our own algorithms to help you make a confident decision on what action to take with a given device or user.
If you'd like to use this mode, go on to step 4.
Step 4: Integrate decisioning from Stytch (optional)
First you'll add an onclick() handler to your login button, or any other flow that you'd like to protect.
Call the async function GetTelemetryID(). This function will promise resolve the telemetry GUID for a give request. You should pass this telemetry GUID along with the sensitive request as an X header or as a URL parameter.
When your backend receives a sensitive request, do the following:
- Extract the telemetry GUID from the header or URL argument.
- Do a Lookup call (see step 5).
- Parse the JSON response and use that data to make your decision.
From Stytch you'll receive one of the following values for action in your Lookup call:
- ALLOW: Stytch has determined that this traffic is from a real human and should be allowed to proceed without any additional friction.
- CHALLENGE: Stytch detected that this traffic came from scripted traffic, e.g. a Python script, or otherwise did not meet our ALLOW ruleset. This attempt should be stepped up in friction, e.g. served a CAPTCHA or be prompted to complete a second authentication factor, before moving forward.
- BLOCK: Stytch detected active tampering or traffic came from an IP address with known bad reputation, e.g. TOR exit nodes. This attempt should be blocked from performing any additional action.
An example of what this might look like:
<html>
<HEAD>
<script src=https://elements.stytch.com/telemetry.js></script>
</HEAD>
<body>
<button id="login" onclick="login()">Click here to log in!</button>
<script>
function login() {
GetTelemetryID().then((session_id) => {
var request = new XMLHttpRequest();
request.open('POST', 'https://www.customer.com/login', true);
request.setRequestHeader('X-Telemetry-ID', session_id);
request.send(null);
});
}
</script>
</body>
</html>
Step 5: Pulling your fingerprinting data
If you're using Collection only, you'll need to pull the data that Stytch collects.
To do this you'll use our Lookup endpoint; as part of your Device Fingerprinting onboarding, we'll send over instructions on how to use our Lookup endpoint and some sample responses that you'll receive.
Step 6: Tying it all together
If you went with Collection only, you now have all of the data you need for your fraud risk team to build smart decisioning models based on the data that you receive from Stytch.
If you went with Collection and decisioning, your backend should be receiving Stytch decisions on each user and device going through your login flow. You can now decide where to introduce friction or outright block suspected bad actors quickly and easily.
Any feedback? We'd love to hear it! Reach out to support@stytch.com.
