Seguridad

Seguridad de API keys

Las API keys son la forma principal de autenticarse con la API de Apertur. Mantenerlas seguras es fundamental para proteger su cuenta y los datos de sus usuarios.

TOTP para API keys

Para una capa adicional de seguridad, puede requerir una contrasena de un solo uso basada en el tiempo (TOTP) con cada solicitud a la API que utilice una clave especifica.

1. Abra la configuracion de su API key y haga clic en Habilitar TOTP.
2. Escanee el QR code con su aplicacion de autenticacion (Google Authenticator, Authy, 1Password, etc.).
3. Ingrese el codigo de 6 digitos para verificar la configuracion.
4. De ahora en adelante, incluya el codigo TOTP en el encabezado X-APTR-TOTP con cada solicitud.

El nombre del encabezado es X-APTR-TOTP. Los codigos son validos por 30 segundos con una tolerancia de un paso de tiempo.

curl -X POST https://api.apertur.ca/v1/sessions \
  -H "Authorization: Bearer aptr_xxxx" \
  -H "X-APTR-TOTP: 123456" \
  -H "Content-Type: application/json" \
  -d '{ "delivery_mode": "webhook", "webhook_url": "https://..." }'

Certificados de cliente (mTLS)

TLS mutuo (mTLS) proporciona el nivel mas alto de autenticacion de API al requerir un certificado de cliente con cada solicitud, ademas de su API key.

1. Genere un certificado de cliente y una clave privada (o use uno emitido por la CA de su organizacion).
2. Suba el certificado a la configuracion de su API key en Certificados de cliente.
3. Apertur validara el certificado en cada solicitud.
4. Incluya tanto el certificado como la clave al realizar llamadas a la API (vea el ejemplo a continuacion).
5. Las solicitudes sin un certificado de cliente valido seran rechazadas con un error 403.

# cURL with client certificate
curl -X POST https://api.apertur.ca/v1/sessions \
  --cert client.crt \
  --key client.key \
  -H "Authorization: Bearer aptr_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "delivery_mode": "webhook", "webhook_url": "https://..." }'

Contrasenas de sesion

Puede proteger sesiones de carga individuales con una contrasena. Cuando se establece, los usuarios finales deben ingresar la contrasena antes de poder subir fotos.

curl -X POST https://api.apertur.ca/v1/sessions \
  -H "Authorization: Bearer aptr_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "delivery_mode": "webhook",
    "webhook_url": "https://your-app.com/webhook",
    "password": "claim-4521-pin"
  }'

Las contrasenas se hashean usando bcrypt en el servidor. Apertur nunca almacena contrasenas en texto plano y no se pueden recuperar despues de la creacion.

SDK Origin Validation

When using the aptr-connect SDK, you can restrict which domains are allowed to use your public key by configuring allowed domains on your OAuth app. The server validates the Origin header of incoming requests against your allowed domains list.

Wildcards are supported: *.example.com matches any subdomain at any depth. Leave the list empty during development to allow all origins.

Configure allowed domains in your partner OAuth app settings.

Verificacion de firmas de webhooks

Cada entrega de webhook incluye un encabezado X-APTR-Signature que contiene una firma HMAC-SHA256 del cuerpo de la solicitud. Verifique esta firma para asegurarse de que el payload fue enviado por Apertur y no ha sido alterado.

const crypto = require("crypto");

function verifyWebhook(body, signatureHeader, secret) {
  const expected = "sha256=" +
    crypto.createHmac("sha256", secret)
      .update(body)
      .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

// In your Express handler:
app.post("/webhook", express.raw({ type: "*/*" }), (req, res) => {
  if (!verifyWebhook(req.body, req.headers["x-aptr-signature"], WEBHOOK_SECRET)) {
    return res.status(401).send("Invalid signature");
  }
  // Safe to process...
  res.status(200).end();
});

import hmac
import hashlib

def verify_webhook(body: bytes, signature: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Seguridad de la cuenta

Mas alla de la seguridad de las API keys, proteja su cuenta de Apertur con estas medidas.