Add external metadata for context

Device Fingerprinting is more useful with the full context of your application. To provide context, you can attach additional metadata to your fingerprints and verdicts.

Without external metadata, it can be difficult to interpret your data. For example, you might see a large volume of lookups for the same fingerprints. Is it because one user is very active and taking many actions on their own account? Or is it because an attacker is creating many different accounts using the same device?

Using the Stytch Dashboard and external metadata, you can understand user behavior and fraud patterns with full context.

The Fingerprint Lookup API has an optional parameter for external_metadata that looks like this:

"external_metadata": {
    "external_id": "user-123",
    "organization_id": "organization-123",
    "user_action": "LOGIN"
}

Each field is optional:

• external_id represents a specific user identifier, like an email address or user ID.
• organization_id represents a group identifier, like an organization or other group.
• user_action represents the action that was fingerprinted.

You can provide any string data in these fields, though you should consider your company's privacy and compliance policy. Stytch Device Fingerprinting stores the external_metadata and does not use it for decisioning or enforcement.

In Protected Auth, Stytch authentication methods are protected using Device Fingerprinting. Each protected method adds external metadata to provide context:

• external_id stores different identifiers depending on the action: the user's email address, biometric registration ID, User ID (for Consumer projects), or Member ID (for B2B projects).
• organization_id stores the member's organization (when using B2B Authentication).
• user_action stores the associated API action (SDK method), like OTPsSMSSend or SDKB2BDiscoveryPasswordReset.

After you start sending external metadata in your Fingerprint Lookup API requests, you will be able to view and query them in the Stytch Dashboard's Device Fingerprinting Logs.

Here are some examples of questions you can ask:

• In a recent spike of signups (user_action), what were the fingerprints? Is there a common pattern in their email addresses or domains (external_id)?
• A specific user recently reported unauthorized activity on their account. Are there different fingerprints associated with their external_id that might indicate an account takeover?
• Recently you've seen more account takeover attempts against one particular business customers (organization_id). Is there a pattern in their fingerprints?

The Stytch Dashboard is a convenient way to perform ad-hoc queries against your recent Device Fingerprinting data. You can also store the Fingerprint Lookup responses yourself and correlate it with your other logs.