Device Fingerprinting Overview

Device Fingerprinting lets you resolve a stable, client-scoped deviceId and curated device signals outside (and beside) payment flows. Your app collects an opaque fingerprint payload with the Stitch SDK; your server-side submits it to the Stitch API over OAuth.

Stitch provisions access and enables the fingerprint endpoints during onboarding.

What you get

Outcome	Description
Fingerprint payload	Base64 JSON from the Stitch SDK (web, iOS, or Android)
id	Stitch event resource id for support and GET by event
deviceId	Opaque device identifier scoped to your client. Stable across frequent use; may be replaced after prolonged inactivity (on the order of months). Persist what you need from each response. On the device resource, the same value appears as id.
signals	Curated device intelligence for an event (or latest snapshot on a device)

Before you start

Stitch provisions the following before integration:

Item	Used by	Notes
clientId	SDK and APIs	UUID assigned by Stitch. Use a live client for production traffic and a test client for integration. The same production API host is used for both.
SDK packages	Mobile / JS	Private packages for web, iOS, and Android (see SDK Integration). Stitch provisions repository access and versions during onboarding; install steps live in Cloudsmith / provisioning docs.
OAuth client	Your server-side only	client_credentials grant with the client_fingerprinting scope.

Test clients and SDK emulation

For SDK emulation, the client id must start with test. Emulation generates a new random fingerprint hash and session on every getDeviceData() call, so each submit mints a new deviceId. That does not mean identity is broken: turn emulation off (or use non-emulated collection) when validating that deviceId is stable across submits.

Components

Surface	Role
Stitch SDK	Collects and may cache device signals locally, and returns a payload to be submitted over Stitch's API. Note that this does not automatically submit fingerprint events to Stitch.
api.stitch.money	Submit fingerprint events; re-read by event id; list events by correlationId or deviceId (paginated); get a device resource by id (same host as other Stitch REST APIs).

Integration flow

Resolution is synchronous. After a successful POST, you may optionally re-read the event by id, list events by correlationId or by deviceId, fetch the latest event with ?deviceId=&limit=1, or fetch the device resource. See Server-side API.

When to submit

Fingerprint on important actions such as login, signup, account recovery, or payment. You can cache and reuse the returned deviceId on your side, but it is recommended to fingerprint again on key actions when you want fresh device signals.

The SDK may collect or cache a fingerprint locally, but it never submits to Stitch on its own. Your server-side submits the event.

Avoid duplicate submits on payments

If a Stitch payment SDK already attaches a fingerprint to a payment request, do not also submit a duplicate event to the standalone fingerprint API for that same payment.

Support

When contacting Stitch, provide:

• Event id (if you received a response)
• correlationId (especially if you sent one and never got an event id)

Nice to have if available: platform, SDK version (sdkVersion in the payload), approximate timestamp, userId, and any error code from a failed request.

Next: SDK packages, then submit events from your server.