Autenticación y claves API

La API de Discuse autentica cada solicitud con una clave API. Envíala en el encabezado de solicitud X-API-Key (o como un campo api_key en el cuerpo JSON). Las claves comienzan con el prefijo disc_, están vinculadas a un único proyecto y solo se muestran completas una vez, al crearlas. Esta guía explica cómo obtenerlas, usarlas, protegerlas y rotarlas.

¿Cómo funciona la autenticación de Discuse?

Cada llamada a la API debe incluir una clave API válida. Discuse la utiliza para:

Registrar el uso en relación con la cuota de tu proyecto
Aplicar límites de frecuencia por clave para evitar abusos
Asociar las solicitudes con el proyecto correcto y su configuración
Controlar el acceso a los recursos de tu cuenta

Cómo obtener tu clave API

Paso 1: Crea una cuenta

Si aún no lo has hecho, regístrate para obtener una cuenta de Discuse en discuse.com. Puedes empezar con el plan Basic gratuito, que incluye una asignación mensual de solicitudes API, además de acceso a comprobaciones de texto, spam, idioma e imágenes. Consulta la página de precios para ver los límites actuales de cada plan.

Paso 2: Accede al panel

Después de iniciar sesión, ve a tu panel. Busca la sección "API Keys" o "Developer" en el menú de navegación.

Paso 3: Genera una clave nueva

Haz clic en "Create New API Key" y, si quieres, proporciona un nombre o una descripción para la clave. Esto te ayuda a identificar el propósito de cada clave si creas varias.

Tu nueva clave API se mostrará una sola vez. Cópiala de inmediato y guárdala de forma segura: no podrás volver a ver la clave completa.

Cómo usar tu clave API

Incluye tu clave API en el encabezado X-API-Key de cada solicitud:

curl -X POST https://api.discuse.com/api/v2/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: disc_aB3dEf6GhIjKlMnOpQrStUvWxYz012345" \
  -d '{
    "content": {
      "text": "Content to analyze"
    }
  }'

También puedes pasar la clave como un campo api_key dentro del cuerpo JSON en lugar de usar el encabezado; se prefiere el encabezado para que la clave nunca termine en registros del cuerpo de la solicitud.

Ejemplo en JavaScript

const response = await fetch('https://api.discuse.com/api/v2/check', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.DISCUSE_API_KEY
  },
  body: JSON.stringify({
    content: { text: 'Content to analyze' }
  })
});

Ejemplo en Python

import requests
import os

response = requests.post(
    'https://api.discuse.com/api/v2/check',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': os.environ['DISCUSE_API_KEY']
    },
    json={
        'content': {'text': 'Content to analyze'}
    }
)

Prácticas recomendadas de seguridad para claves API

Nunca expongas claves en código del lado del cliente

Las claves API nunca deben incluirse en JavaScript que se ejecuta en el navegador. El código del lado del cliente es visible para cualquiera que vea el código fuente de tu página.

// WRONG - Don't do this!
const API_KEY = 'disc_aB3dEf6...'; // Exposed in browser

// CORRECT - Use a backend proxy
const response = await fetch('/api/moderate', {
  method: 'POST',
  body: JSON.stringify({ text: userInput })
});

Usa variables de entorno

Guarda las claves API en variables de entorno, no en tu base de código:

# .env file (add to .gitignore!)
DISCUSE_API_KEY=disc_aB3dEf6GhIjKlMnOpQrStUvWxYz012345

// Access in Node.js
const apiKey = process.env.DISCUSE_API_KEY;

Rota las claves con regularidad

Rota periódicamente tus claves API, especialmente si sospechas que pueden haberse visto comprometidas:

Genera una clave API nueva
Actualiza tu aplicación para que use la nueva clave
Verifica que todo funcione correctamente
Revoca la clave antigua

Nota: una clave revocada puede seguir siendo utilizable durante hasta unos 5 minutos porque las claves validadas se almacenan en caché. Planifica las rotaciones teniendo en cuenta ese breve solapamiento, en lugar de esperar un cambio instantáneo.

Usa claves separadas para distintos entornos

Crea claves API diferentes para desarrollo, staging y producción:

Entorno	Propósito de la clave
Desarrollo	Pruebas y desarrollo local
Staging	Pruebas previas a producción
Producción	Tráfico de la aplicación en vivo

Esto te permite revocar una clave comprometida sin afectar a otros entornos.

¿Cómo funcionan los límites de frecuencia?

Los límites de frecuencia se aplican por clave API, no por plan. Cada clave tiene un límite de solicitudes por minuto (RPM) definido al crearla; si no especificas uno, el valor predeterminado es 60 solicitudes por minuto. Distintas claves de la misma cuenta pueden tener límites diferentes, de modo que puedes asignar un RPM más alto a un servicio de alto rendimiento que a una integración puntual.

Cuando una clave supera su límite de RPM, la solicitud falla con un estado HTTP 429 Too Many Requests cuyo message indica que se superó el límite de frecuencia. Los contadores de límites de frecuencia se reinician en una ventana móvil de un minuto.

Cómo gestionar los límites de frecuencia

Espera y reintenta cuando recibas un 429 (y también ante 5xx transitorios). Como la ventana es de un minuto, funciona bien un retroceso exponencial que empiece en torno a un segundo y vaya aumentando:

async function checkWithRetry(content, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch('https://api.discuse.com/api/v2/check', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': process.env.DISCUSE_API_KEY
      },
      body: JSON.stringify({ content })
    });

    if (response.status === 429 || response.status >= 500) {
      const delay = 1000 * Math.pow(2, attempt); // 1s, 2s, 4s
      await new Promise(resolve => setTimeout(resolve, delay));
      continue;
    }

    return response.json();
  }
  throw new Error('Max retries exceeded');
}

¿Qué respuestas de error puedo recibir?

Situación	Estado HTTP
Solicitud mal formada (contenido vacío, texto de más de 10 000 caracteres, demasiadas URLs)	`400` validación de solicitud
Clave API ausente o no válida	`401`
Límite de frecuencia superado para la clave	`429`
Cuota del período de facturación agotada	`200` con un `message` y `usage` (no es un estado de error)

El agotamiento de la cuota no se trata intencionadamente como un error HTTP: la respuesta de /api/v2/check sigue devolviendo 200 con has_violations: false, un message que describe la cuota agotada y un objeto usage que muestra api_requests_remaining: 0. Revisa esos campos en lugar de depender de un código de estado. Los fallos de autenticación devuelven 401, los límites de frecuencia 429 y los fallos de validación de solicitudes 400. Consulta la referencia de Códigos de error y respuesta para ver la lista completa.

Gestión de varias claves

Para equipos más grandes o aplicaciones complejas, puede que necesites varias claves API:

Casos de uso para varias claves

Claves por entorno: Claves separadas para desarrollo, staging y producción
Claves por servicio: Claves distintas para diferentes microservicios
Claves por equipo: Aísla el uso por equipo para la facturación interna
Claves temporales: Claves de corta duración para contratistas o integraciones

Prácticas recomendadas para la gestión de claves

Nombra las claves de forma descriptiva: "Production - User Service", "Staging - Backend"
Documenta el uso de las claves: Mantén registros de qué clave se usa en cada lugar
Configura alertas: Supervisa patrones de uso inusuales
Auditorías periódicas: Revisa y elimina las claves sin usar cada trimestre

Próximos pasos

Guía de inicio rápido - Haz tu primera llamada a la API
Análisis de texto - Aprende sobre la detección de sentimiento
Escalado de la moderación de contenido - Patrones de implementación de alto volumen