> ## 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

> API de huella de conexión de VU: identifica un dispositivo por su firma TLS, sus cabeceras y su origen geográfico, sin JavaScript de rastreo.

**Connection Fingerprint** identifica un dispositivo por cómo se conecta, no por lo que declara ser. En una única llamada devuelve la firma TLS del cliente, la firma de sus cabeceras HTTP, su origen geográfico aproximado y un identificador persistente —todo derivado del propio handshake de la conexión—.

Sirve para reconocer un dispositivo que vuelve, detectar automatización que se hace pasar por un navegador y sumar señales a un motor de riesgo. No requiere SDK, no ejecuta código en el cliente y no depende de las APIs del navegador que los modos de privacidad bloquean.

<Note>
  Las señales de esta API son **insumo para decidir**, no un veredicto. A diferencia de [Antispoofing Facial](/vucs/antispoofing-facial/introduccion), aquí no hay un campo que diga «sospechoso»: usted combina estas señales con su propia lógica de riesgo.
</Note>

## Cómo funciona

```mermaid theme={null}
sequenceDiagram
    participant N as Navegador o cliente
    participant F as Connection Fingerprint
    participant B as Su backend
    N->>F: GET / (con cookie fp si ya existe)
    F-->>N: { userData, signature } + Set-Cookie fp
    N->>B: Envía la respuesta completa
    B->>B: Verifica la firma y evalúa el riesgo
```

El cliente llama al servicio directamente: la huella se deriva de **esa** conexión TLS, así que una llamada hecha desde su servidor describiría a su servidor, no al usuario. La respuesta viaja después a su backend, donde se verifica y se usa.

## Endpoints

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

| Método | Ruta | Autenticación | Para qué sirve |
| - | - | - | - |
| `GET` | `/` | Ninguna | Obtener la huella de la conexión actual. |
| `GET` | `/version` | Ninguna | Versión del servicio. |
| `GET` | `/publicKey` | Ninguna | Clave pública RSA para verificar `signature`. |
| `GET` | `/update` | `X-API-Key` | Operación administrativa de VU. No forma parte del flujo de integración. |

<Note>
  `/`, `/version` y `/publicKey` son públicos por diseño: el navegador del usuario final tiene que poder llamarlos sin credenciales. Lo que protege la integración no es una api-key, sino la verificación de la firma en su backend.
</Note>

## Primera llamada

```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..."
}
```

## Anatomía de la respuesta

### Identidad de la conexión

| Campo | Qué es |
| - | - |
| `tlsFingerprint` | La huella JA3 completa del cliente: versión, cifrados, extensiones y curvas ofrecidas en el handshake TLS, en ese orden. |
| `tlsFingerprintHash` | Hash MD5 de la anterior. Es el valor práctico para comparar y agrupar. |
| `tlsFingerprintSslGreased` | `"1"` si el cliente usó valores GREASE (RFC 8701). Los navegadores modernos lo hacen; muchas bibliotecas HTTP no. |
| `http2Fingerprint` / `http2FingerprintHash` | Huella de la capa HTTP/2. `null` cuando la conexión no llegó por HTTP/2. |
| `headers` | Las cabeceras que el cliente envió, tal como llegaron. |
| `headerSignature` | Hash del conjunto de cabeceras: su orden y presencia son tan característicos como su contenido. |

<Tip>
  La señal más útil no es un campo suelto, sino la **coherencia entre ellos**. Un `user-agent` que dice Chrome junto a un `tlsFingerprintHash` que no corresponde a ningún Chrome conocido, o con `tlsFingerprintSslGreased` en `"0"`, describe un cliente que declara ser algo que no es.
</Tip>

### Persistencia

| Campo | Qué es |
| - | - |
| `cookie` | Identificador persistente. El servicio lo emite en una cookie `fp` con un año de vigencia, `HttpOnly`, `Secure` y `SameSite=None`. |
| `etag` | Identificador basado en el mecanismo de caché HTTP. Sobrevive al borrado de cookies en varios navegadores. |
| `etagFirstRequest` | `true` cuando el `etag` se emitió en esta llamada; `false` cuando el cliente lo devolvió, es decir, ya había estado antes. |

### Origen

| Campo | Qué es |
| - | - |
| `ip` | Dirección de origen observada. |
| `geoData.accuracyRadius` | Radio de precisión en kilómetros. **Léalo siempre junto a las coordenadas.** |
| `geoData.latitude` / `longitude` | Centro del área estimada, no la posición del dispositivo. |
| `geoData.country` / `countryIso` | País y su código ISO 3166-1 alfa-2. |
| `geoData.subdivisions` / `subdivisionsIso` | División administrativa y su código. |
| `geoData.city` | Ciudad. **Frecuentemente `null`.** |

<Warning>
  La geolocalización por IP es aproximada y varios de sus campos pueden llegar en `null`. Trate cada clave de `geoData` como opcional y nunca la use como única prueba de ubicación: una VPN, una red corporativa o un CGNAT desplazan el resultado cientos de kilómetros sin que nada en la respuesta lo indique.
</Warning>

### Integridad

`signature` es una firma RSA de 4096 bits producida con la clave privada de VU sobre el bloque `userData`. Existe porque la respuesta pasa por el cliente antes de llegar a su backend, y el cliente es exactamente la parte en la que no conviene confiar.

<Card title="Integración" icon="code" href="/vucs/connection-fingerprint/integracion">
  Cómo llamarla desde el navegador, qué hacer con la respuesta y cómo usar las señales.
</Card>


## Related topics

- [Integrar Connection Fingerprint](/vucs/connection-fingerprint/integracion.md)
- [VU Cloud Services](/vucs/introduccion.md)
- [Documentación técnica de VU](/index.md)
- [Changelog de Identity Link API](/identity-link/changelog.md)
- [Leer resultados KYC de verificaciones de identidad](/identity-link/kyc.md)


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