@innerworks-me/iw-auth-sdk

docs.innerworks.me

Innerworks Web SDK

Innerworks provides market-leading device fingerprinting and VPN detection.

True device fingerprinting enables platforms to detect and block repeat fraudsters, even if they change accounts, wallets, or even their location — all without adding user friction or compromising user privacy.

Installation

NPM

npm install @innerworks-me/iw-auth-sdk

Yarn

yarn add @innerworks-me/iw-auth-sdk

Bun

bun add @innerworks-me/iw-auth-sdk

Content Security Policy (CSP)

The Innerworks SDK uses a dynamic loading mechanism to keep the core metrics collection system always up to date to ensure the most accurate results and browser compatibility.

[!NOTE]
By default, browser CSP rules are permissive. If your website does not enforce a Content Security Policy, no additional configuration is required. The Innerworks SDK uses a dynamic loading mechanism to fetch the latest SDK-Core logic from our CDN at runtime. This ensures you always have access to the most up-to-date detection capabilities without requiring manual SDK updates

Strict CSP Configuration

If your website enforces strict CSP rules, you must whitelist our CDN domain as a trusted JavaScript source. Add sdk-cdn.prod.innerworks.me to your script-src or default-src directive.

Example CSP header with script-src:

Content-Security-Policy: script-src 'self' https://sdk-cdn.prod.innerworks.me;

Example CSP header with default-src:

Content-Security-Policy: default-src 'self' https://sdk-cdn.prod.innerworks.me;

Example meta tag:

<meta http-equiv="Content-Security-Policy" content="script-src 'self' https://sdk-cdn.prod.innerworks.me;">

If you are using both directives, add the domain to script-src as it takes precedence over default-src for script loading.

Initialise the SDK

The innerworks SDK must be instantiated after page load with you project id.

React

import { InnerworksMetrics } from "@innerworks-me/iw-auth-sdk";

function InnerworksComponent() {
  const [innerworksMetrics, setInnerworksMetrics] = useState<InnerworksMetrics|null>();

  useEffect(() => {
    setInnerworksMetrics(
      new InnerworksMetrics({
        appId: 'your-project-id'
      })
    );
  }, []);
  
  return <div></div>
}

Angular

import { InnerworksMetrics } from "@innerworks-me/iw-auth-sdk";

class MyComponent implements AfterViewInit {
  innerworksMetrics: InnerworksMetrics | null = null;

  ngAfterViewInit(): void {
    this.innerworksMetrics = new InnerworksMetrics({
      appId: 'your-project-id',
    });
  }
}

IFrame integration

You can embed the Innerworks SDK without significant modifications to your codebase by simply embedding an iframe.

See docs.innerworks.me/iframe for more information.

Sending Data

Once the SDK is initialised, data must be sent at the point at which you want to analyse the user's session.

if (innerworksMetrics) {
  await innerworksMetrics.send('user-id');
}

The user-id is used to associate data with a user on your platform. This is typically a UUID that you have access to. Examples include web3 wallet addresses, and usernames.

[!WARNING] Avoid using any personal data for the user-id, including but not limited to email addresses, names, or other identifiers that can be used to identify an individual. Innerworks does not agree to process personal data entered here.

Receiving Results

Fingerprinting

For fingerprinting, you can use the requestId to retrieve the fingerprint and any additional data via an additional request.

const {
  result,
  requestId,
} = await innerworksMetrics.send('user-id');
if (result === 'success') {
  // use the requestId from your backend
}

See the API Access docs for how to use this requestId.

[!IMPORTANT] For security reasons, the fingerprint is not provided directly to the frontend in the response, and should be requested separately from the backend.

VPN Detection

VPN results are returned directly from the SDK via a JWT. For more information on how to validate the JWT, see our JWT Verification guide.

import { InnerworksResponse } from "@innerworks-me/iw-auth-sdk";
import { jwtDecode } from "jwt-decode";

const { result, detectionResult }: InnerworksResponse = await innerworksMetrics.send('user-id');
if (result === 'success') {
  const data = jwtDecode(detectionResult);
  const {
    vpnIsEnabled,
    trueGeoLocationName,
    trueGeoLocationCode,
    vpnLocationCode,
    stateUS,
  } = data.detection_result
}

Next steps

• To access fingerprinting information, see our API Access guide
• To validate the JWT returned from the SDK, see our JWT Verification guide