Autenticación

Clave de API

Guardian usa una clave de API sp_live_* proporcionada por el equipo de Surt, pero en la v0.3.0 esa clave la maneja únicamente tu backend. Se usa para generar JWTs de corta duración y nunca se entrega al cliente (app móvil o web). El cliente solo maneja los JWTs de corta duración que tu backend le entrega.

Obtención de 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. Navega a Settings → Developer
4. Copia tu clave de API y almacénala como un secreto del lado del servidor

Cómo funciona la autenticación (v0.3.0)

1. Tu backend maneja 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:

• JWT fresco por cada verify(): cada JWT es de un solo uso; reutilizar uno es rechazado por el backend.
• El JWT de collect() es opcional: pásalo solo para incrustar la IP pública del dispositivo en el payload. Como collect() genera su propio nonce, su JWT puede reutilizarse u omitirse por completo.

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

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.

Tokens de acceso a paquetes

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

Plataforma	Tipo de token	Dónde configurar
React Native	Token npm	.npmrc en la raíz del proyecto
iOS	Token GitHub	~/.netrc
Android	Token GitHub	gradle.properties

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

• React Native
• iOS
• Android

Entornos

Entorno	URL base	Uso
production	https://api.surt.com	Tráfico en vivo
sandbox	https://sandbox-api.surt.com	Pruebas y desarrollo

aviso

Mantén tu clave de API sp_live_* del lado del servidor en todo momento; se usa únicamente para generar JWTs de corta duración. Nunca la incrustes en el código del cliente de la app o web. El cliente solo maneja JWTs de corta duración.