Autenticación — API de Zelta Forms

La API de Zelta Forms utiliza autenticación basada en tokens Bearer (OAuth 2.0) para proteger el acceso a los recursos.

Obtener un token de acceso

Paso 1: Crear una aplicación API

1. Ve a Ajustes > API > Aplicaciones.
2. Haz clic en + Nueva aplicación.
3. Completa los datos:
   • Nombre de la aplicación
   • URL de redirección (para flujo OAuth)
   • Scopes requeridos
4. Guarda y copia tu client_id y client_secret.

Seguridad

El client_secret solo se muestra una vez al momento de crearlo. Guárdalo en un lugar seguro. Si lo pierdes, deberás generar uno nuevo.

Paso 2: Solicitar un token

Realiza una petición POST al endpoint de autenticación:

curl -X POST https://api.zelta.dev/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "tu_client_id",
    "client_secret": "tu_client_secret",
    "scope": "forms:read forms:write"
  }'

Respuesta exitosa

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "forms:read forms:write"
}

Paso 3: Usar el token

Incluye el token en el header Authorization de cada petición:

curl -X GET https://api.zelta.dev/v1/forms \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Scopes disponibles

Scope	Descripción	Permisos
forms:read	Lectura de formularios y respuestas	Consultar formularios, campos y respuestas.
forms:write	Escritura de formularios	Crear y actualizar formularios y campos.
forms:admin	Administración completa	Eliminar formularios, gestionar configuraciones y exportar datos.

Principio de mínimo privilegio

Solicita únicamente los scopes que tu aplicación necesita. Si solo necesitas leer respuestas, usa forms:read.

Renovación de tokens

Los tokens tienen una vigencia de 1 hora (3600 segundos). Para renovar:

curl -X POST https://api.zelta.dev/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "tu_refresh_token",
    "client_id": "tu_client_id"
  }'

Errores de autenticación

Código HTTP	Error	Descripción
401	unauthorized	Token ausente, expirado o inválido.
403	forbidden	El token no tiene los scopes necesarios.
429	rate_limited	Se excedió el límite de peticiones.

Ejemplo de error

{
  "error": "unauthorized",
  "message": "El token de acceso ha expirado.",
  "hint": "Solicita un nuevo token usando tu refresh_token."
}

Límites de tasa (Rate Limiting)

Plan	Límite
Starter	60 peticiones/minuto
Business	300 peticiones/minuto
Enterprise	1,000 peticiones/minuto

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

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 285
X-RateLimit-Reset: 1709145600

Consejo

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