Introducción

La API de Sparker Verify proporciona acceso programático a la verificación criptográfica de medios. Todos los endpoints se sirven a través de HTTPS desde https://verify.sparker.io/api/v1.

La API sigue las convenciones REST con cuerpos de solicitud y respuesta en formato JSON. Se utiliza multipart/form-data para las cargas de archivos.

URL Base: https://verify.sparker.io/api/v1

Autenticación

Sparker tiene dos modos de autenticación. La gestión del panel de control utiliza Google OAuth y tokens portadores JWT. El tráfico del SDK debe usar claves de API generadas desde el panel en la cabecera Authorization.

Los endpoints de verificación pública se pueden invocar sin autenticación, pero esas solicitudes están mucho más limitadas en velocidad que las que incluyen una clave de API.

Flujo de OAuth

1. Redirigir al usuario a GET /api/v1/auth/google
2. El usuario se autentica con Google
3. La redirección de retorno vuelve a su app con el access_token
4. Incluir el token en las solicitudes posteriores

GET /api/v1/auth/me

Obtener el usuario autenticado actual.

curl https://verify.sparker.io/api/v1/auth/me \
  -H "Authorization: Bearer su-jwt-access-token"

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "usuario@example.com",
  "name": "Jane Doe",
  "avatar_url": "https://lh3.googleusercontent.com/...",
  "oauth_provider": "google",
  "email_verified": true,
  "created_at": "2026-01-15T10:30:00Z"
}

POST /api/v1/auth/refresh

Refrescar un token de acceso expirado usando la cookie del token de actualización.

POST /api/v1/auth/logout

Invalidar la sesión actual y limpiar el token de actualización.

Claves de API

Cree claves de API desde el panel de control, luego inicialice el SDK con esa clave y reutilice el cliente en su aplicación.

POST /api/v1/api-keys

Crear una nueva clave de API. El valor completo de la clave solo se devuelve una vez.

curl -X POST https://verify.sparker.io/api/v1/api-keys \
  -H "Authorization: Bearer su-jwt-access-token" \
  -H "Content-Type: application/json" \
  -d '{"name": "SDK de Producción"}'

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "SDK de Producción",
  "key_prefix": "spk_live_abc123",
  "key": "spk_live_abc123def456ghi789...",
  "is_active": true,
  "created_at": "2026-01-15T10:30:00Z",
  "last_used_at": null,
  "revoked_at": null
}

GET /api/v1/api-keys

Listar las claves de API activas para el usuario del panel autenticado.

DELETE /api/v1/api-keys/:id

Revocar una clave de API. Devuelve 204 No Content.

Registro de Dispositivos del Navegador

Los dispositivos deben registrarse con atestación de hardware antes de poder firmar medios. Cada dispositivo genera un par de claves ECDSA P-256 a través de WebAuthn. Este flujo de producción actualmente solo es compatible con entornos web/navegador; las plataformas nativas iOS y Android no están soportadas todavía.

POST /api/v1/devices/challenge

Generar un desafío para el registro de dispositivo. El cliente firma este desafío con la clave privada del dispositivo durante el registro WebAuthn. Acepta una clave de API en Authorization o un token de enlace 3P enX-Token.

{
  "challenge": "dGhpcyBpcyBhIGNoYWxsZW5nZQ..."
}

POST /api/v1/devices/register

Registrar un dispositivo con prueba de atestación y clave pública. Acepta una clave de API en Authorization o un token de enlace 3P enX-Token.

curl -X POST https://verify.sparker.io/api/v1/devices/register \
  -H "Authorization: Bearer spk_live_su_clave_api" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "web",
    "device_id": "credential-id-base64",
    "public_key": {
      "algorithm": "ES256",
      "x": "base64-x-coordinate",
      "y": "base64-y-coordinate"
    },
    "attestation": {
      "format": "webauthn",
      "data": "attestation-object-base64",
      "challenge_response": "client-data-json-base64"
    },
    "device_info": {
      "name": "Chrome on macOS",
      "model": "Chrome",
      "os_version": "macOS 15.3"
    }
  }'

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "device_id": "credential-id-base64",
  "name": "Chrome on macOS",
  "model": "Chrome",
  "platform": "web",
  "registered_at": "2026-01-15T10:30:00Z"
}

GET /api/v1/devices

Listar todos los dispositivos registrados para el usuario autenticado.

DELETE /api/v1/devices/:id

Eliminar un dispositivo registrado.

Verificaciones

El flujo de verificación consta de dos pasos: crear una solicitud de verificación para obtener un nonce, y luego enviar el medio firmado para completar la verificación.

POST /api/v1/verifications

Crear una solicitud de verificación. Devuelve un nonce que debe ser firmado junto con el medio. El nonce expira en 5 minutos.

curl -X POST https://verify.sparker.io/api/v1/verifications \
  -H "Authorization: Bearer spk_live_su_clave_api"

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "nonce": "random-nonce-base64",
  "expires_at": "2026-01-15T10:35:00Z"
}

POST /api/v1/verifications/verify

Enviar el medio firmado para completar la verificación. Utiliza multipart form data. La firma debe ser Sign(Hash(file + nonce)) usando la clave privada del dispositivo.

curl -X POST https://verify.sparker.io/api/v1/verifications/verify \
  -H "Authorization: Bearer spk_live_su_clave_api" \
  -F "id=550e8400-e29b-41d4-a716-446655440000" \
  -F "file=@photo.jpg" \
  -F "device_id=credential-id-base64" \
  -F "signature=signature-base64" \
  -F 'metadata={"latitude":37.7749,"longitude":-122.4194}'

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "authentic": true,
  "signature_hash": "abc123def4567890abc123def4567890abc123def4567890abc123def4567890",
  "verified_at": "2026-01-15T10:31:00Z",
  "device": {
    "name": "Chrome on macOS",
    "model": "Chrome",
    "platform": "web"
  },
  "gps": {
    "latitude": 37.7749,
    "longitude": -122.4194,
    "accuracy": 10.0
  }
}

GET /api/v1/verifications/:id

Obtener detalles de la verificación por ID.

Enlaces de Verificación 3P

Los enlaces de verificación 3P permiten al titular de una cuenta delegar los flujos de captura a terceros. Las verificaciones creadas a través de estos enlaces se descuentan de la cuota del creador del token.

POST /api/v1/verifications/external

Crear un nuevo enlace de verificación 3P. Requiere un plan Pro o Enterprise.

curl -X POST https://verify.sparker.io/api/v1/verifications/external \
  -H "Authorization: Bearer spk_live_su_clave_api" \
  -H "Content-Type: application/json" \
  -d '{"max_uses": 10, "expires_at": "2026-02-01T00:00:00Z"}'

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "token": "spk_abc123def456...",
  "url": "https://verify.sparker.io/capture?token=spk_abc123def456...",
  "max_uses": 10,
  "expires_at": "2026-02-01T00:00:00Z",
  "created_at": "2026-01-15T10:30:00Z"
}

GET /api/v1/verifications/external

Listar todos los enlaces de verificación 3P para la cuenta autenticada.

DELETE /api/v1/verifications/external/:id

Revocar un token activo. Devuelve 204 No Content.

GET /api/v1/verifications/external/validate/:token

Validar un token de enlace de verificación 3P. Endpoint público (no requiere autenticación).

{
  "valid": true,
  "creator_name": "Jane Doe",
  "remaining_uses": 8,
  "expires_at": "2026-06-15T10:30:00Z"
}

Verificación Pública

Cualquier persona puede verificar la autenticidad de los medios utilizando estos endpoints públicos. El SDK extrae los hashes de firma localmente para que los archivos nunca tengan que subirse para ser verificados. Estos endpoints se pueden invocar sin autenticación, pero agregar una clave de API desbloquea límites de solicitud mucho más altos. El servidor acepta el hash de la firma del dispositivo o el hash del archivo almacenado como clave de búsqueda pública.

POST /api/v1/verify

Comprobar si un hash de búsqueda público está registrado.

curl -X POST https://verify.sparker.io/api/v1/verify \
  -H "Content-Type: application/json" \
  -d '{"signature_hash": "abc123def4567890abc123def4567890abc123def4567890abc123def4567890"}'

{
  "authentic": true,
  "verification_id": "550e8400-e29b-41d4-a716-446655440000",
  "verified_at": "2026-01-15T10:31:00Z"
}

GET /api/v1/verify/:id

Obtener detalles completos de la verificación, incluyendo GPS, información del dispositivo y el manifiesto C2PA para un registro de verificación público o 3P.

POST /api/v1/verify/batch

Verificar hasta 100 hashes de firma en una sola solicitud.

Cuota de Uso

Cada usuario tiene una cuota mensual de verificaciones basada en su plan. Las cuotas se restablecen el día 1 de cada mes a la medianoche UTC.

GET /api/v1/quota

Obtener el estado actual de la cuota para el usuario autenticado.

Límites de Velocidad

Los límites de velocidad varían según el estado de autenticación. Cuando se supera el límite, la API devuelve 429 Too Many Requests con una cabeceraRetry-After.

Errores

La API utiliza códigos de estado HTTP estándar para indicar el éxito o el fracaso de las solicitudes. Las respuestas de error contienen un objeto JSON con un mensaje descriptivo.