Integración con un agente de programación con IA

Muchos equipos integran FingerTrackID con un agente de programación con IA. Esta página proporciona al agente la documentación en el formato que mejor lee y las reglas que no debe incumplir. Las instrucciones de la integración en sí siguen estando en la entrega de la implementación.

Inicio rápido

1. Descargue el archivo de integración. En la consola, Integração e saúde › Arquivo da integração descarga fingertrackid.integration.json. Lo genera un administrador de la empresa o un gestor de integración. Guárdelo en la raíz del repositorio que integra FingerTrackID (el archivo de integración).

2. Guarde el secreto usted mismo. Quien recibió el secreto HMAC una sola vez en la consola lo guarda directamente en el gestor de secretos del backend, desde donde el backend lo lee como FTID_HMAC_SECRET_HEX. Nunca se entrega al agente (lo que nunca se entrega a una IA).

3. Añada el servidor MCP a su agente. En Claude Code, desde la raíz del repositorio:

   claude mcp add --scope project fingertrackid -- npx -y @fingertrackid/mcp@0.1.3

   Los demás clientes están en el servidor MCP. Un agente sin MCP lee, en su lugar, /llms-full.txt y el archivo de integración.

4. Dé las reglas al agente. Pegue el bloque de reglas en AGENTS.md, CLAUDE.md o el equivalente de su herramienta.

5. Pida al agente que haga la integración. En Claude Code, ejecute el prompt del servidor con sus etiquetas, separadas por comas:

   /mcp__fingertrackid__integrate_fingertrackid login,withdrawal

   En otro agente, o sin MCP, pegue el prompt de integración. El agente lee el archivo de integración y añade una llamada fail-open por etiqueta con el SDK de servidor. Después incorpora el token del Web SDK a su solicitud existente y valida un cuerpo de solicitud sintético.

6. Compruebe usted mismo la credencial real. Canalice el secreto desde su gestor de secretos hacia npx --no fingertrackid-server check (cómo). Envía una evaluación real en modo shadow e imprime el veredicto. Después, revise el trabajo del agente antes del tráfico real.

El prompt de integración

Copie este prompt en su agente de programación con IA, desde la raíz del repositorio que contiene su sitio y su backend. Funciona con o sin el servidor MCP. El agente se detiene para pedir su confirmación antes de editar nada y nunca necesita el secreto.

Prompt de integración

Péguelo en su agente de programación con IA o ábralo en uno.

Integrate FingerTrackID into this project, in shadow mode: FingerTrackID recommends, and our
system keeps deciding and acting as it does today.

Sources, in this order:
- The fingertrackid MCP server, when it is connected: start with ftid_read_manifest.
- fingertrackid.integration.json at the repository root: the issued values (API origin,
  application public key, allowed origins, collection origin, key_id, Web SDK package). Never
  invent them or copy them from an example.
- The documentation, https://docs.fingertrackid.com/llms-full.txt. The published contracts win
  over any prose or example.

Never ask for, print, log, commit or store the HMAC secret. The backend reads it at runtime, by
name, as FTID_HMAC_SECRET_HEX from our secret manager. If a step needs its value, stop and tell me.

Show me your plan before you edit anything, then work in this order:

1. Inventory. Find where users sign in (including MFA and redirects such as Google sign-in), sign
   up, recover a password and take sensitive actions (withdrawals, transfers, changes of email,
   phone or password). Propose one lowercase tag per moment, such as login, signup,
   password_recovery or withdrawal, using the FingerTrackID templates. Wait for my confirmation.
2. Missing inputs. Check the integration file. If the collection origin, a server credential with
   assessment:write or the Web SDK package is missing, tell me what to do in the console, and
   continue only with the work that does not depend on it.
3. Backend. In Node.js, install the server SDK with the exact version:
   npm install --save-exact @fingertrackid/server@0.1.2
   Create one module with one function per tag (the MCP tool ftid_server_recipe generates it).
   In another language, implement the signature from
   https://docs.fingertrackid.com/api/authentication/ and match the public test vector first.
   - Call each function after our own checks and before our product acts: for login, after the
     real authentication and MFA. Keep our own decision.
   - Fail open: when FingerTrackID is slow, unavailable or misconfigured, the product works as
     today, and the failure is logged without secrets.
   - subject_ref and account_ref are keyed pseudonyms the backend derives, for example
     HMAC-SHA-256 of our internal ID with a key only the backend holds. Never an email, tax ID,
     phone number or name.
   - Log only identifiers and verdicts: tag, result kind, assessment_id, recommended action and
     correlation ID. Never the token, the signature or the request body.
   - When a result is UNAVAILABLE or UNEXPECTED_RESPONSE, keep result.operation with our record
     so it can be resent.
4. Browser. Install the private Web SDK archive named in the integration file's sdk_package. A
   person downloads it from the console. Verify its SHA-256 and SHA-512 against the file, then
   run npm install --save-exact --ignore-scripts ./fingertrackid-sdk-web.tgz. Never install a
   public package with a similar name. Then follow
   https://docs.fingertrackid.com/web-sdk/collection/#the-recipe:
   - one module with initializeSdk, only in browser code, with the publicKey and
     collectionOrigin from the integration file, and createActionContextHelper;
   - prefetch() on the first focus or pointer-down of each assessed form, never at page load,
     and only after any consent our privacy rules require;
   - take() once per submit;
   - the token and its expiresAt, or null, sent inside the existing authenticated,
     CSRF-protected request;
   - the helper closed on logout or account switch.
   The SDK never reads form values or passwords.
5. Site configuration. Add the collection origin to connect-src in our Content-Security-Policy.
   Keep that origin out of tracing header propagation (Sentry tracePropagationTargets, Datadog
   allowedTracingUrls, OpenTelemetry propagateTraceHeaderCorsUrls).
6. Checks.
   - Run npx --no fingertrackid-server self-check.
   - Validate one synthetic request body (ftid_validate_request in the MCP server).
   - Add tests for the fail-open paths: FingerTrackID unavailable, and a null token.
   - Run our test suite.
7. Hand-off.
   - List every file you changed, and what I must still do in the console.
   - Ask me to run npx --no fingertrackid-server check with the secret piped from our secret
     manager. It sends one real assessment in shadow mode.

Documentación para el agente

Archivo	Contenido	Úselo para
/llms.txt	Un resumen breve de la plataforma, sus reglas y un enlace a cada conjunto de documentación	El punto de partida del agente
/llms-full.txt	Todas las páginas de este sitio en un solo archivo de texto plano	Un trabajo de integración completo
/llms-small.txt	Las mismas páginas, con los espacios en blanco eliminados; se conservan todas las notas, advertencias y secciones desplegables	Ventanas de contexto más pequeñas

Los tres archivos se generan a partir de estas páginas en cada publicación, por lo que no dicen nada que las páginas no digan. Los contratos publicados (OpenAPI y JSON Schema, enlazados desde la visión general de la API) prevalecen sobre cualquier texto o ejemplo, en estos archivos y en todas las páginas.

El archivo de integración

En la consola, Integração e saúde › Arquivo da integração (también en Início, en el paso del SDK) descarga fingertrackid.integration.json. Guárdelo en la raíz del repositorio que integra FingerTrackID: el agente lee de él los valores emitidos en lugar de copiarlos a mano.

Campo	Contenido
api_origin, documentation, request_profile	El origen de la API de producción, esta documentación para agentes y el perfil de solicitud que se debe enviar
secret	Solo el nombre de la variable de la que el backend lee el secreto, FTID_HMAC_SECRET_HEX. Nunca el secreto
application	El ID, el slug, el nombre, el entorno, la clave pública del navegador y los orígenes permitidos de la aplicación
collection	El origen de captura first-party confirmado, o null hasta que el dominio de captura esté activo
server_credentials	El key_id, las capacidades y la tasa aprobada de cada credencial de servidor vigente
sdk_package	La versión, el SHA-256 y el SHA-512 del archivo aprobado del Web SDK, o null

El archivo contiene solo identificadores públicos, por lo que puede versionarse en el repositorio. Descárguelo de nuevo cuando cambie una clave, el paquete del SDK o los orígenes: no se actualiza solo. Su contrato es el esquema del manifiesto de integración.

El servidor MCP

@fingertrackid/mcp es un servidor local de Model Context Protocol para agentes de programación compatibles con MCP. Se ejecuta en la máquina del desarrollador mediante stdio, lee el archivo de integración y los valores públicos, y no modifica nada. Ninguna herramienta acepta el secreto HMAC.

Añádalo con la versión exacta. En Claude Code, para este proyecto:

claude mcp add --scope project fingertrackid -- npx -y @fingertrackid/mcp@0.1.3

Otros clientes que leen un archivo mcpServers, como .mcp.json:

{
  "mcpServers": {
    "fingertrackid": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@fingertrackid/mcp@0.1.3"]
    }
  }
}

Inicie el agente desde la raíz del repositorio, donde está el archivo de integración. Después, pídale que ejecute el prompt integrate_fingertrackid o que use las herramientas directamente:

Herramienta	Qué hace
ftid_read_manifest	Lee el archivo de integración y enumera lo que todavía falta en la consola
ftid_list_templates	Los diez momentos habituales para evaluar, con la etiqueta sugerida y las referencias (plantillas)
ftid_server_recipe	Un módulo TypeScript completo para el SDK de servidor, con una función fail-open por etiqueta
ftid_validate_request	Comprueba un cuerpo de solicitud exactamente como lo lee la API
ftid_explain_signature	Las diez líneas canónicas y el MAC de un cuerpo, con el secreto de prueba público
ftid_check_vector_mac	Compara un firmador en cualquier lenguaje con el vector de prueba público
ftid_interpret_response	Explica una evaluación o un Problem, y si se debe reintentar
ftid_check_collection_domain	Lee el DNS y el TLS públicos de su dominio de captura, solo para un dominio de los orígenes de la aplicación en el archivo de integración

El servidor también ofrece los contratos públicos como recursos. Todas las herramientas son de solo lectura; la primera llamada real se sigue ejecutando desde su backend, con el secreto que este lee de su gestor de secretos.

Reglas para su repositorio

Pegue este bloque en el archivo de instrucciones que lee su agente (AGENTS.md, CLAUDE.md o el equivalente de su herramienta), en el repositorio que llama a FingerTrackID.

Reglas del repositorio

Péguelas en AGENTS.md, CLAUDE.md o el equivalente de su herramienta.

## FingerTrackID integration

Documentation: https://docs.fingertrackid.com/llms-full.txt. The published contracts win over
any prose or example.

- Shadow mode. FingerTrackID recommends; this system decides and executes every action. Never
  block, allow, hold or settle anything because of a recommendation unless the product team
  decided it explicitly.
- Fail open. If FingerTrackID is slow, unavailable or misconfigured, the product keeps working
  with its own decision, and the failure is reported, not hidden.
- HMAC secret. Read it at runtime from the server-side secret manager, by name. Never ask for
  its value, and never print, log, commit or store it, or put it in a test, fixture, example or
  browser-exposed variable.
- Issued values. The key_id, the browser public key, the collection origin and the DNS records
  come from the FingerTrackID console. Never take them from a documentation example or from
  another application.
- Signing. FTID-HMAC-SHA256-V1 over the decoded secret bytes, never the hexadecimal text.
  Reproduce the published test vector byte for byte before the first real call.
- Body. Serialize it once. A retry resends the same bytes with a new X-FTID-Request-Id
  (UUIDv7), the current X-FTID-Timestamp and a new signature. Content-Type is exactly
  application/json, with no Content-Encoding.
- References. subject_ref and account_ref are keyed pseudonyms created by this backend (for
  example HMAC-SHA-256 of the internal ID with a backend key). Never send an email, tax ID,
  phone number, name or account number. account_ref requires subject_ref.
- Browser token. The event_context_token goes from the browser SDK to this backend inside the
  existing authenticated, CSRF-protected request. It is not a result; never log it.
- Response. trust_score null means no score, never 0 or 100, and INCONCLUSIVE is a normal
  outcome. Keep X-Correlation-Id for support.
- Logs. Never log the secret, the token, the signature or the full request body.

Lo que nunca se entrega a una IA

• El secreto HMAC. Un administrador de la empresa o un gestor de integración lo recibe una sola vez en la consola y lo guarda directamente en el gestor de secretos del backend. El agente escribe código que lo lee por su nombre; nunca necesita el valor.
• Datos reales de usuarios. Los logs de producción, los cuerpos de solicitud con referencias reales, los tokens de contexto del evento y las exportaciones de la consola se mantienen fuera de los prompts y del contexto del agente.
• Acceso a la consola. Su contraseña, los códigos de su autenticador y su sesión en la consola son personales.

Un agente que pide el secreto

Si un agente pide el valor del secreto para probar una llamada, la respuesta es no. El agente comprueba su código de firma con el vector de prueba y la autocomprobación públicos, que usan un secreto sintético que no autentica nada. La primera llamada real se ejecuta desde su backend, con el secreto que este lee de su gestor de secretos.

Cómo revisar el trabajo del agente

• La autocomprobación de la firma imprime el MAC esperado en el Node.js que ejecuta su backend.
• La guía de integración trata el comportamiento fail-open, el presupuesto de tiempo y las pruebas en producción sin sandbox.
• La lista de verificación de integración es la lista de revisión antes del tráfico real.