Integrar Identity Link con un asistente de IA

Si programas con un asistente de IA, puedes pedirle la integración de Identity Link en una sola frase. La skill de Identity Link es un conjunto de instrucciones y una referencia de la API que tu asistente lee antes de escribir código. Con ella, el asistente conoce las reglas de la API que no se descubren probando, como validar la firma del webhook o recuperar un resultado cuyo aviso no llegó.

> Integra Identity Link en mi app

El asistente escribe la integración en tu proyecto, en tu lenguaje y tu framework. Si no indicas ninguno, usa Node.js con TypeScript.

Instalar la skill

La skill está publicada en el repositorio público vusecurity/VU-ONE de GitHub. Se instala con un comando. Necesitas Node.js para usar npx. Ejecuta el comando en la carpeta raíz de tu proyecto:

npx skills add vusecurity/VU-ONE

El instalador detecta los asistentes de tu equipo y copia la skill en la carpeta de cada uno, por ejemplo .claude/skills/ para Claude Code o .agents/skills/ para otros asistentes compatibles. Funciona con Claude Code, Codex, Cursor y otros asistentes que leen skills.

Instalar para todos tus proyectos

Agrega -g para instalar la skill en tu usuario en lugar de en el proyecto:

npx skills add vusecurity/VU-ONE -g

Instalar para un solo asistente

Indica el asistente con -a:

npx skills add vusecurity/VU-ONE -a claude-code

Actualizar a la última versión

npx skills update

La versión de la skill está en el encabezado de su archivo SKILL.md. La versión publicada es la 1.0.0.

Usar la skill

Ten a mano tus credenciales

Necesitas una cuenta de Identity Link. El plan free alcanza para una prueba de concepto. En el portal, abre Ajustes → Desarrolladores. Ahí están el Client Id, el Client Secret y el Webhook Secret.El asistente te pide que los guardes en variables de entorno: IDENTITY_LINK_CLIENT_ID, IDENTITY_LINK_CLIENT_SECRET e IDENTITY_LINK_WEBHOOK_SECRET. No los pegues en el chat ni en el código.

Pide la integración

Escribe el pedido en español o en inglés. Por ejemplo: «Integra Identity Link en mi app para verificar a los usuarios nuevos». La skill se activa sola cuando el pedido es una integración de Identity Link.

Revisa lo que armó

Revisa el código antes de llevarlo a producción. La skill tiene una lista de verificación final que el asistente recorre contigo.

Prueba de punta a punta

Crea un enlace, ábrelo en un teléfono y completa la verificación. Confirma que llega el webhook y que tu aplicación lee y guarda el resultado. Para recibir el webhook en tu equipo, usa un túnel como ngrok o cloudflared. Cuando termines la prueba, elimina ese endpoint con DELETE /webhook-endpoints/{id}.

Qué queda armado en tu proyecto

Credenciales y token

Las credenciales se leen de variables de entorno y la aplicación no arranca si falta una. El token se guarda en caché y se renueva antes de vencer.

Enlace de verificación

POST /links con un externalUserId que sale de la sesión de tu servidor, nunca del navegador. Tu aplicación entrega linkUrl a la persona.

Webhook con la firma validada

El endpoint se registra una sola vez. El handler valida X-Signature-SHA256 sobre el body raw, en tiempo constante, y responde 200 enseguida.

Resultado guardado

Ante un evento terminal, la aplicación lee GET /verifications/{id} en el momento y guarda en tu sistema solo lo que necesitas.

Reglas que el asistente aplica

La skill reúne en un solo lugar las reglas de la API que una integración tiene que respetar para funcionar en producción. Estas son las principales:

Regla	Por qué importa
Validar la firma del webhook sobre el body raw, antes de parsearlo	Sin esa validación, cualquiera puede marcar a un usuario como verificado
Todas las llamadas y los secretos quedan en tu servidor	Un secreto dentro de una app web o móvil es público
Registrar el endpoint de webhook una sola vez	Cada registro repetido entrega cada evento otra vez
Reconciliar las verificaciones abiertas al iniciar y cada pocos minutos	Un webhook tiene 3 intentos de entrega. Si fallan, el evento se pierde
Leer el resultado enseguida	En el plan free, el resultado se conserva 30 minutos después de terminar la verificación. Después, la API responde `410`
Una verificación fallida no vuelve a exitosa	Tu cuenta puede marcar como fallida una verificación que terminó bien. El registro conserva `status: "success"` y suma `feedback.status: "failed"`
Tratar los errores de cupo como cupo agotado	`POST /links` responde `409` y una captura en curso responde `403`. El `409` trae cuándo se renueva el cupo
No guardar en logs los webhooks, los registros ni `linkUrl`	Quien tiene el enlace puede completar la verificación

Detalle de cada tema en Webhooks, KYC y Errores.

Cuándo se activa

La skill se activa con pedidos para integrar Identity Link en el código de una aplicación: crear enlaces, recibir y validar webhooks, leer un resultado o armar una prueba de concepto en el plan free. No se activa para:

VU Cloud Services, las APIs con Api-Key como ID Analysis, Face Analysis o Antispoofing Facial.
El login de VU ONE o sus tenants.
Usar el portal de Identity Link sin programar.

Cómo se identifican las llamadas

El código que arma el asistente envía el encabezado User-Agent: identity-link-skill/<versión> en cada llamada a la API. Así VU distingue las integraciones hechas con la skill y su versión. El encabezado no lleva datos personales.

Qué sigue

Introducción

El flujo completo de la integración.

Webhooks

Eventos, firma y reintentos.

Repositorio de la skill

El código fuente de la skill en GitHub.

Primeros Pasos

Conceptos Clave

Referencia