Autenticación

Todas las solicitudes a la API de NueForm requieren autenticación mediante claves de API. Esta guía cubre cómo generar claves, usarlas en solicitudes y mantenerlas seguras.

Generación de claves de API

Para crear una clave de API:

1. Inicia sesión en tu cuenta de NueForm.
2. Navega a Perfil y abre la pestaña Desarrollador.
3. Haz clic en Crear clave de API.
4. Dale a tu clave un nombre descriptivo (por ejemplo, "Backend de producción" o "Pipeline CI").
5. Copia la clave inmediatamente --- solo se mostrará una vez.

Formato de clave de API

Las claves de API de NueForm siguen un formato consistente:

nf_<64 caracteres hexadecimales>

Cada clave comienza con el prefijo nf_ seguido de 64 caracteres hexadecimales (32 bytes aleatorios). Por ejemplo:

nf_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

En el panel de control, las claves se identifican por su prefijo (los primeros 11 caracteres, por ejemplo, nf_a1b2c3d4) para que puedas distinguirlas sin exponer el valor completo.

Uso de tu clave de API

Incluye tu clave de API en el encabezado Authorization de cada solicitud usando el esquema Bearer:

Authorization: Bearer nf_tu_clave_de_api_aqui

cURL

curl -X GET https://app.nueform.com/api/v1/forms \
  -H "Authorization: Bearer nf_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json"

JavaScript (fetch)

const NUEFORM_API_KEY = process.env.NUEFORM_API_KEY;

const response = await fetch("https://app.nueform.com/api/v1/forms", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${NUEFORM_API_KEY}`,
    "Content-Type": "application/json",
  },
});

const { data } = await response.json();
console.log(data);

Python (requests)

import os
import requests

api_key = os.environ["NUEFORM_API_KEY"]

response = requests.get(
    "https://app.nueform.com/api/v1/forms",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
)

data = response.json()["data"]
print(data)

Errores de autenticación

Si la autenticación falla, la API devuelve una respuesta 401 Unauthorized con un mensaje descriptivo:

Ejemplo de respuesta de error:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API key.",
    "status": 401
  }
}

Gestión de claves

Límites

Cada cuenta de NueForm puede tener hasta 10 claves de API activas en cualquier momento. Si necesitas crear una nueva clave y has alcanzado el límite, revoca una clave existente primero.

Revocación de claves

Puedes revocar una clave de API en cualquier momento desde la pestaña Desarrollador en tu perfil. La revocación es inmediata --- cualquier solicitud que use una clave revocada recibirá una respuesta 401 Unauthorized.

Para revocar una clave:

1. Ve a Perfil > Desarrollador.
2. Busca la clave que deseas revocar (identificada por su nombre y prefijo).
3. Haz clic en Revocar.
4. Confirma la acción.

Seguimiento de último uso

NueForm registra la última vez que se usó cada clave de API. Consulta la pestaña Desarrollador para ver qué claves están en uso activo y cuáles pueden ser seguras para revocar.

Requisitos de plan

El acceso a la API es una función restringida que requiere un plan de pago:

Si intentas usar una clave de API en una cuenta cuyo plan no incluye acceso a la API, recibirás una respuesta 403 Forbidden:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API access is not available on your current plan.",
    "status": 403
  }
}

Mejores prácticas de seguridad

Sigue estas directrices para mantener tus claves de API seguras:

Nunca subas claves al control de versiones

Agrega tus archivos de claves a .gitignore y usa variables de entorno en su lugar. Si una clave se sube accidentalmente, revócala inmediatamente y genera una nueva.

# .env (agrega .env a tu .gitignore)
NUEFORM_API_KEY=nf_tu_clave_de_api_aqui

Usa variables de entorno

Almacena las claves de API en variables de entorno en todos los entornos --- desarrollo local, staging y producción. Nunca codifiques las claves directamente en el código fuente de tu aplicación.

// Correcto
const apiKey = process.env.NUEFORM_API_KEY;

// Incorrecto --- nunca hagas esto
const apiKey = "nf_a1b2c3d4...";

Usa claves separadas para cada entorno

Crea claves de API distintas para desarrollo, staging y producción. Esto limita el alcance del daño si una clave se ve comprometida y facilita revocar el acceso de un solo entorno.

Rota las claves periódicamente

Crea nuevas claves periódicamente y retira las antiguas. NueForm permite hasta 10 claves activas, por lo que puedes crear una nueva clave, actualizar tus servicios, verificar que todo funcione y luego revocar la clave anterior.

Restringe el uso solo al lado del servidor

Las claves de API solo deben usarse en código del lado del servidor. Nunca expongas tu clave de API en JavaScript del lado del cliente, aplicaciones móviles o cualquier código que se ejecute en el navegador del usuario.