> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vu-one.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connection Fingerprint

> VU's connection fingerprinting API: identifies a device by its TLS signature, its headers, and its geographic origin — with no tracking JavaScript.

**Connection Fingerprint** identifies a device by how it connects, not by what it claims to be. In a single call it returns the client's TLS signature, the signature of its HTTP headers, its approximate geographic origin, and a persistent identifier — all derived from the connection handshake itself.

Use it to recognize a returning device, detect automation posing as a browser, and add signals to a risk engine. No SDK, no code executed on the client, and no dependence on the browser APIs that privacy modes block.

<Note>
  These signals are **input for a decision**, not a verdict. Unlike [Facial Antispoofing](/en/vucs/antispoofing-face/introduction), there is no field here that says "suspicious": you combine these signals with your own risk logic.
</Note>

## How it works

```mermaid theme={null}
sequenceDiagram
    participant B as Browser or client
    participant F as Connection Fingerprint
    participant S as Your backend
    B->>F: GET / (with the fp cookie if one exists)
    F-->>B: { userData, signature } + Set-Cookie fp
    B->>S: Forwards the full response
    S->>S: Verifies the signature and scores the risk
```

The client calls the service directly: the fingerprint is derived from **that** TLS connection, so a call made from your server would describe your server, not the user. The response then travels to your backend, where it is verified and used.

## Endpoints

Base URL: `https://fingerprint.api.vusecurity.com`

| Method | Path | Auth | What it's for |
| - | - | - | - |
| `GET` | `/` | None | Get the fingerprint of the current connection. |
| `GET` | `/version` | None | Service version. |
| `GET` | `/publicKey` | None | RSA public key used to verify `signature`. |
| `GET` | `/update` | `X-API-Key` | VU administrative operation. Not part of the integration flow. |

<Note>
  `/`, `/version`, and `/publicKey` are public by design: the end user's browser has to be able to call them without credentials. What secures the integration is not an api-key — it is verifying the signature in your backend.
</Note>

## First call

```bash theme={null}
curl -s https://fingerprint.api.vusecurity.com/
```

```json theme={null}
{
  "userData": {
    "timeStampUtc": "2026-08-22T13:19:24.013555",
    "http2Fingerprint": null,
    "http2FingerprintHash": null,
    "tlsFingerprint": "771,4866-4865-49196-49195-49200-49199-...",
    "tlsFingerprintHash": "2800f914a7a4ba98aa9df62d316a460c",
    "tlsFingerprintSslGreased": "0",
    "headers": {
      "x-forwarded-for": "203.0.113.42",
      "host": "fingerprint.api.vusecurity.com",
      "user-agent": "Mozilla/5.0 ...",
      "accept": "*/*"
    },
    "headerSignature": "dd847632ef6fa4c27394ea149c58f34a",
    "etag": "UNTLLK5S-21550",
    "etagFirstRequest": true,
    "geoData": {
      "accuracyRadius": 10,
      "latitude": -36.0,
      "longitude": -59.9964,
      "country": "Argentina",
      "countryIso": "AR",
      "city": null,
      "subdivisions": "Buenos Aires",
      "subdivisionsIso": "B"
    },
    "ip": "203.0.113.42",
    "cookie": "8L3KA06LD6I9N4PUUOV5SQ74Y6H78Q7Z"
  },
  "signature": "Fdnb/bD3UGWmkcUByAmWahDXLADJJa0qCFubqr0ESnTW..."
}
```

## Anatomy of the response

### Connection identity

| Field | What it is |
| - | - |
| `tlsFingerprint` | The client's full JA3 fingerprint: version, ciphers, extensions, and curves offered during the TLS handshake, in that order. |
| `tlsFingerprintHash` | MD5 hash of the above. This is the practical value for comparing and grouping. |
| `tlsFingerprintSslGreased` | `"1"` when the client used GREASE values (RFC 8701). Modern browsers do; many HTTP libraries do not. |
| `http2Fingerprint` / `http2FingerprintHash` | Fingerprint of the HTTP/2 layer. `null` when the connection did not arrive over HTTP/2. |
| `headers` | The headers the client sent, exactly as received. |
| `headerSignature` | Hash of the header set: their order and presence are as characteristic as their contents. |

<Tip>
  The most useful signal is not any single field — it is the **coherence between them**. A `user-agent` claiming to be Chrome alongside a `tlsFingerprintHash` that matches no known Chrome, or with `tlsFingerprintSslGreased` at `"0"`, describes a client claiming to be something it is not.
</Tip>

### Persistence

| Field | What it is |
| - | - |
| `cookie` | Persistent identifier. The service issues it in an `fp` cookie valid for one year, `HttpOnly`, `Secure`, `SameSite=None`. |
| `etag` | Identifier based on the HTTP cache mechanism. It survives cookie clearing in several browsers. |
| `etagFirstRequest` | `true` when the `etag` was issued on this call; `false` when the client sent one back — meaning it had been here before. |

### Origin

| Field | What it is |
| - | - |
| `ip` | Observed source address. |
| `geoData.accuracyRadius` | Accuracy radius in kilometres. **Always read it alongside the coordinates.** |
| `geoData.latitude` / `longitude` | Centre of the estimated area, not the device's position. |
| `geoData.country` / `countryIso` | Country and its ISO 3166-1 alpha-2 code. |
| `geoData.subdivisions` / `subdivisionsIso` | Administrative subdivision and its code. |
| `geoData.city` | City. **Frequently `null`.** |

<Warning>
  IP geolocation is approximate and several of its fields can arrive as `null`. Treat every key in `geoData` as optional, and never use it as sole proof of location: a VPN, a corporate network, or CGNAT will shift the result by hundreds of kilometres with nothing in the response to indicate it.
</Warning>

### Integrity

`signature` is a 4096-bit RSA signature produced with VU's private key over the `userData` block. It exists because the response passes through the client on its way to your backend, and the client is precisely the party you should not trust.

<Card title="Integration" icon="code" href="/en/vucs/connection-fingerprint/integration">
  How to call it from the browser, what to do with the response, and how to use the signals.
</Card>


## Related topics

- [Integrate Connection Fingerprint](/en/vucs/connection-fingerprint/integration.md)
- [VU Cloud Services](/en/vucs/introduction.md)
- [VU Technical Documentation](/en/index.md)
- [Identity Link API Changelog](/en/identity-link/changelog.md)
- [Errors and diagnostics](/en/vucs/antispoofing-face/errors.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.