Seguridad

La autorización es solo por clave

El contrato define exactamente dos esquemas de seguridad, y ambos llevan el mismo secreto:

Esquema	Encabezado	Notas
`ApiKeyHeader`	`X-API-Key`	Recomendado.
`BearerAuth`	`Authorization: Bearer`	Equivalente. Úsalo cuando una biblioteca cliente exija un token de portador.

Cualquiera de las dos formas resuelve a la misma credencial. GET /v1/products es el único endpoint que acepta una llamada sin autenticar.

No hay lista de IP permitidas. El límite de tasa por IP es un techo compartido por todo lo que está detrás de una misma dirección — acota el abuso, no concede ni deniega acceso. Trata la clave como toda la frontera de autoridad de tu cuenta.

La clave

Una clave API de Zelnum es ck_ seguida de 48 caracteres: 51 en total. Algo más corto no es una clave, lo cual es una comprobación útil cuando un gestor de secretos estropea un valor.

Correcto	Incorrecto
Mantenerla en un gestor de secretos o en una variable de entorno	Ponerla en un repositorio, en un archivo de configuración que los usuarios puedan leer o en un registro de CI
Enviarla desde tu servidor	Ponerla en JavaScript del navegador, en el paquete de una app móvil o en cualquier cliente público
Leer `api_key_id` cuando necesites identificar la clave	Pegar la clave en sí en una solicitud de soporte
Redactarla en los registros	Registrar los encabezados completos de las solicitudes

Una clave dentro del paquete de un front-end no es un secreto. Si una integración necesita llamar a la API desde un navegador, el navegador debería llamar a tu propio servidor y tu servidor debería custodiar la clave — el techo por IP sobre el tráfico que parece no autenticado no te salvará.

La base de datos almacena un hash SHA-256 y un prefijo visible de 9 caracteres, nunca el valor en sí, así que un volcado filtrado no entrega a nadie un token utilizable. La otra cara es que ningún endpoint puede devolver tu clave: si la pierdes, la rotas.

Confirmar qué clave está activa

curl -X GET "https://api.zelnum.com/api/v1/api-key" \
  -H "X-API-Key: YOUR_KEY_HERE"

La respuesta incluye api_key_id, masked_key, last_used y created_at — de la clave activa emitida más recientemente en la cuenta. El endpoint informa de una sola clave, así que léelo como «la clave que estaría usando ahora mismo», no como un inventario. Para ver todas las claves, usa la Consola.

last_used es la forma más rápida de confirmar que una rotación surtió efecto, con una salvedad: se escribe como máximo una vez cada cinco minutos por clave, así que una clave que se usa mucho puede seguir apareciendo como intacta hasta cinco minutos después de que cambies a ella. No concluyas que un despliegue está roto solo por un last_used desactualizado.

Rotar una clave

Una cuenta puede tener varias claves activas a la vez, y la Consola las gestiona individualmente:

Acción en la Consola	Efecto
Crear	Añade una clave. Todas las claves existentes siguen funcionando.
Regenerar	Desactiva esa clave y emite un reemplazo con el mismo nombre. La original deja de funcionar de inmediato.
Eliminar	Elimina una clave por completo.

Eso te da dos formas de rotación, y la elección depende de si puedes permitirte una ventana de solapamiento.

Crear una segunda clave — la rotación por etapas, y la preferible:

Crea la clave nueva en la Consola. Nada más cambia; la clave antigua todavía autentica.
Prepara el valor nuevo en todos los lugares donde se necesite — servidores de aplicaciones, procesos de trabajo, tareas cron, secuencias de comandos programadas — sin activarlo todavía.
Conmuta los despliegues. Verifica con GET /v1/api-key hasta que informe del nuevo api_key_id, teniendo en cuenta la granularidad de cinco minutos de last_used.
Elimina la clave antigua cuando ya nada la esté usando. Este es el paso que realmente elimina la credencial — una rotación no termina hasta que se hace.

Regenerar in situ — cuando el valor antiguo debe desaparecer ya:

Úsalo cuando una clave quedó expuesta y cualquier validez continuada es un riesgo.

Acepta el hueco. La clave antigua deja de funcionar en el instante en que regeneras, así que todos los componentes que aún la conserven devolverán 401 unauthorized hasta que se vuelvan a desplegar. No hay solapamiento, por diseño.
Regenera en la Consola y copia el valor en texto plano del aviso de inmediato — se muestra ahí y en ningún otro lugar, nunca más.
Despliega el valor nuevo y luego confirma que nada siga registrando 401.

Transporte

Todos los endpoints son HTTPS. No existe ningún puerto a la escucha en texto plano y ningún endpoint acepta una degradación, así que no hay configuración en la que una clave viaje sin cifrar.

Si montas un proxy o una pasarela delante de la API, termina TLS en el borde y reenvía el encabezado X-API-Key — no lo reescribas ni lo añadas a los registros de solicitudes entrantes.

Qué envías y cuánto tiempo se conserva

Las entradas de la API son números de teléfono y direcciones de correo electrónico — datos personales en la mayoría de jurisdicciones. Dos consecuencias:

Envía solo lo que necesitas. Una comprobación requiere el identificador y nada más. No añadas un id de usuario, una referencia interna ni metadatos de texto libre al cuerpo de una solicitud: no se almacenan como campo, solo amplían la exposición de tus propios registros.
Conoce las ventanas de retención. Los registros en tiempo real y los resultados de repetición de idempotencia se conservan 30 días de forma predeterminada, y los archivos de resultados masivos 7 días (result_retention_days). Pasadas esas ventanas los registros desaparecen, así que exporta todo lo que estés obligado a conservar.

Trata el número como sensible también en tus propios sistemas. Un resultado de detección indica a un observador si una persona concreta está registrada en una plataforma concreta, y el par de identificador y veredicto revela más que cualquiera de las dos mitades.

Protegerse contra el doble cobro

Esto es una propiedad de seguridad tanto como de facturación: Idempotency-Key hace seguro un reintento, de modo que un fallo de red o un operador impaciente no pueden convertir un cobro en dos. Nunca generes una clave nueva para reintentar una solicitud cuyo resultado no observaste — consulta Idempotencia y reintentos.

Estado y soporte — qué incluir cuando escalas, sin filtrar la clave
Códigos de error — unauthorized y account_banned en contexto