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
- Contacta al equipo de Surt para obtener las credenciales de tu organización
- Inicia sesión en tu panel de Surt
- Ve a Settings → Developer
- Copia tu clave de API y guárdala como un secreto del lado del servidor
Cómo funciona la autenticación
- Tu backend tiene la clave de API
sp_live_*(secreto del lado del servidor). - Antes de llamar a
verify(), tu app solicita un token a tu propio backend. - Tu backend llama a
POST /geolocation/preflightconAuthorization: Bearer <api key>y el contexto de la transacción, y luego devuelvedata.token(el JWT) a la app. - 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"
}
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
customer_id | string | No | Tu 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_type | string | Sí | login, sign_up, deposit, withdrawal, o una cadena personalizada de hasta 64 caracteres. Consulta Tipos de transacción. |
transaction_name | string | No | Etiqueta legible para personas |
name | string | No | El nombre del cliente |
email | string | No | El correo electrónico del cliente. Una cadena vacía cuenta como ausente. Una dirección inválida devuelve 400. |
phone | string | No | El 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_id | string | No | Solo 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ódigo | Cuándo |
|---|---|
400 | JSON malformado, falta transaction_type, o email, phone o transaction_type inválidos |
401 | La solicitud no tiene el encabezado Authorization |
403 | La clave de API es inválida o está inactiva, o Guardian no está habilitado para tu organización |
503 | Fallo 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_idque 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
geolocationJwtque pasas acollect(), 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:
| Plataforma | Tipo de token | Dónde configurarlo |
|---|---|---|
| React Native | Token npm | .npmrc en la raíz del proyecto |
| iOS | Token de GitHub | ~/.netrc |
| Android | Token de GitHub | gradle.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.
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.