Saltar al contenido principal
Version: Guardian v0.5.3

Autenticación

Clave de API​

Guardian usa una clave de API sp_live_* proporcionada por el equipo de Surt. Solo tu backend tiene esa clave. Tu backend la usa para solicitar JWTs, y nunca se envía al cliente (app móvil o web). El cliente solo maneja los JWTs que le entrega tu backend.

Cómo obtener tu clave de API​

  1. Contacta al equipo de Surt para obtener las credenciales de tu organización
  2. Inicia sesión en tu panel de Surt
  3. Ve a Settings → Developer
  4. Copia tu clave de API y guárdala como un secreto del lado del servidor

Cómo funciona la autenticación​

  1. Tu backend tiene la clave de API sp_live_* (secreto del lado del servidor).
  2. Antes de llamar a verify(), tu app solicita un token a tu propio backend.
  3. Tu backend llama a POST /geolocation/preflight con Authorization: Bearer <api key> y el contexto de la transacción, y luego devuelve data.token (el JWT) a la app.
  4. Tu app pasa el JWT a verify(jwt).

Notas:

  • Un JWT por transacción. Solicita un JWT nuevo para cada transacción. Un JWT expira 30 minutos después de emitirse.
  • El JWT de collect() es opcional. Pásalo para resolver la IP pública del dispositivo e incluirla en el payload y para aplicar la configuración de atestación de tu organización. Consulta Collect (Servidor a servidor).

Solicitud de preflight​

POST https://api.surt.com/geolocation/preflight
Authorization: Bearer sp_live_xxx
Content-Type: application/json

{
"customer_id": "user_abc123",
"transaction_type": "login",
"transaction_name": "User Login",
"name": "John Doe",
"email": "john@example.com",
"phone": "+15555550100"
}
CampoTipoRequeridoDescripción
customer_idstringNoTu identificador de usuario. Omítelo, o envía una cadena vacía, para una transacción anónima, por ejemplo antes del inicio de sesión.
transaction_typestringSílogin, sign_up, deposit, withdrawal, o una cadena personalizada de hasta 64 caracteres. Consulta Tipos de transacción.
transaction_namestringNoEtiqueta legible para personas
namestringNoEl nombre del cliente
emailstringNoEl correo electrónico del cliente. Una cadena vacía cuenta como ausente. Una dirección inválida devuelve 400.
phonestringNoEl número de teléfono del cliente. Una cadena vacía cuenta como ausente. Un número que no se puede interpretar devuelve 400.
install_idstringNoSolo Guardian Web. Consulta Install id web.

Respuesta:

{
"data": {
"token": "<jwt>"
}
}

El contexto del cliente y de la transacción vive en los claims del JWT (establecidos por tu backend en el momento del preflight), por lo que el cliente nunca pasa un ID de cliente ni un tipo de transacción.

data.token expira 30 minutos después de emitirse.

CódigoCuándo
400JSON malformado, falta transaction_type, o email, phone o transaction_type inválidos
401La solicitud no tiene el encabezado Authorization
403La clave de API es inválida o está inactiva, o Guardian no está habilitado para tu organización
503Fallo temporal. Reintenta la solicitud.

Consulta Códigos de error para ver los cuerpos de respuesta.

Install id web (v0.5.0)​

Guardian Web v0.5.0 añade un install_id opcional a preflight para que la identidad de dispositivo de un navegador pueda persistirse en una cookie de origen propio (first-party) y sobreviva a la eliminación del almacenamiento. Aplica solo a @surtai/guardian-web; los SDKs nativos lo ignoran.

  • Solicitud - incluye el install_id que tu backend leyó de su cookie de origen propio (omítelo en la primera visita):

    {
    "customer_id": "user_abc123",
    "transaction_type": "login",
    "install_id": "<id from your first-party cookie, or omit>"
    }
  • Respuesta - preflight devuelve ese mismo id (o genera uno nuevo) y también lo incrusta como un claim del JWT. El SDK web lee el claim del geolocationJwt que pasas a collect(), y solo cuando el navegador no tiene un install id almacenado. Vuelve a establecer tu cookie de origen propio a partir de él:

    {
    "data": {
    "token": "<jwt, now carrying an install_id claim>",
    "install_id": "<id to store in your first-party cookie>"
    }
    }

Esto es opcional: la web funciona sin ello. Consulta Guardian Web → Migrar de v0.4 → v0.5 para ver el flujo completo y la retransmisión de la cookie de ~5 líneas.

Tokens de acceso a paquetes​

El SDK se distribuye como un paquete privado. También recibirás tokens de acceso para la instalación de paquetes. Estos son independientes de la clave de API anterior:

PlataformaTipo de tokenDónde configurarlo
React NativeToken npm.npmrc en la raíz del proyecto
iOSToken de GitHub~/.netrc
AndroidToken de GitHubgradle.properties

Consulta las guías de instalación de cada plataforma para más detalles:

URL base​

El SDK siempre apunta a producción en https://api.surt.com.

aviso

Mantén tu clave de API sp_live_* del lado del servidor en todo momento. Se usa solo para generar JWTs. Nunca la incluyas en el código de la app ni del cliente web. El cliente solo maneja JWTs, que expiran después de 30 minutos.