Autenticación — API de Zelta Forms

La API de Zelta Forms utiliza API Keys para autenticar las peticiones. Las claves se gestionan desde el dashboard de tu workspace.

Plan requerido

El acceso a la API requiere un plan que incluya la función API Access (planes Pro y superiores).

Crear una API Key

1. Ve a Dashboard > Configuración > API (o Dashboard > API Docs).
2. Haz clic en Crear API Key.
3. Asigna un nombre descriptivo (ej. "Integración CRM", "App Móvil").
4. Selecciona los permisos necesarios.
5. Opcionalmente, establece una fecha de expiración.
6. Guarda y copia la clave generada.

Seguridad

La clave completa solo se muestra una vez al momento de crearla. Guárdala en un lugar seguro. Si la pierdes, deberás revocarla y crear una nueva.

Formato de la clave

Las API Keys tienen el prefijo fai_sk_ seguido de un identificador único:

fai_sk_a1b2c3d4e5f6g7h8i9j0...

La clave se almacena internamente como un hash SHA-256 — Zelta nunca guarda la clave en texto plano.

Usar la API Key

Incluye la clave en el header X-API-Key de cada petición:

curl -X GET https://tu-dominio.com/api/v1/forms \
  -H "X-API-Key: fai_sk_tu_clave_aqui"

Ejemplo con JavaScript

const response = await fetch('/api/v1/forms', {
  headers: {
    'X-API-Key': 'fai_sk_tu_clave_aqui'
  }
});
const data = await response.json();

Permisos

Al crear una API Key, seleccionas qué operaciones puede realizar. Los permisos se validan en cada petición contra el workspace asociado a la clave.

Principio de mínimo privilegio

Crea claves con solo los permisos que tu integración necesita. Si solo consultas respuestas, no otorgues permisos de escritura.

Gestionar API Keys

Desde el panel de API Keys en tu dashboard puedes:

Acción	Descripción
Ver claves	Lista todas las API Keys del workspace con nombre, prefijo, última vez usada y estado
Revocar	Desactiva una clave sin eliminarla
Eliminar	Elimina la clave permanentemente

Cada clave muestra su prefijo (primeros caracteres) para identificarla, y registra la última vez que fue utilizada.

Errores de autenticación

Código HTTP	Descripción
401	API Key ausente, inválida, revocada o expirada
403	La clave no tiene los permisos necesarios, o el plan del workspace no incluye acceso API
429	Se excedió el límite de peticiones por minuto

Ejemplo de error

{
  "error": "Unauthorized",
  "message": "API key is invalid or has been revoked."
}

Límites de tasa (Rate Limiting)

Plan	Límite
Free	30 peticiones/minuto
Pro	100 peticiones/minuto
Business	500 peticiones/minuto

Los headers de respuesta incluyen información sobre tu consumo:

X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1709145600

Header	Descripción
X-RateLimit-Remaining	Peticiones restantes en la ventana actual
X-RateLimit-Reset	Timestamp Unix de cuando se reinicia el contador

Consejo

Implementa un mecanismo de reintento exponencial (exponential backoff) para manejar errores 429 de manera elegante.