Autenticación

Usa una clave de API para tu propio backend o para automatizaciones. Usa OAuth cuando tu aplicación pida a otros usuarios de Make Agent Fast que le concedan acceso. Ambos tipos de credenciales llaman a los mismos recursos de /api/v1 y respetan los mismos permisos, derechos del plan, aislamiento entre tenants y límites de frecuencia.

Claves de API#

Se requiere un plan de pago activo para crear y usar una clave de API pública.

1. Abre Panel → Ajustes → Desarrollador.
2. Introduce un nombre que identifique el servicio y el entorno, como Production lead export.
3. Selecciona los permisos mínimos que necesita el servicio.
4. Elige una caducidad: 30 días, 90 días, un año o sin caducidad.
5. Crea la clave y copia de inmediato el valor maf_live_....

Make Agent Fast almacena un hash SHA-256 en lugar de texto plano recuperable. Más adelante, el panel muestra un prefijo seguro, los permisos, la caducidad, la fecha de último uso y el estado de revocación.

Authorization: Bearer maf_live_...

Envía el encabezado desde código de servidor:

curl --fail-with-body https://makeagent.fast/api/v1/me \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Accept: application/json"

Si faltan las credenciales, se devuelve 401 authentication_required. Las claves no válidas, caducadas o revocadas devuelven 401 invalid_api_key. Una clave cuya cuenta ya no tiene un plan de pago activo devuelve 403 subscription_required.

Rotar o revocar una clave#

Crea una clave de reemplazo antes de revocar la anterior. Despliega la nueva clave, haz una solicitud real, verifica su x-request-id y después haz clic en Revocar en la clave anterior. La revocación es inmediata y no se puede deshacer.

En los ajustes de Desarrollador, Editar te permite cambiar el nombre y los permisos de una clave activa; el cambio se aplica de inmediato a esa misma clave. No se pueden cambiar su caducidad ni su token: crea una clave de reemplazo para obtener una nueva caducidad o un token rotado.

Aplicaciones OAuth#

OAuth está pensado para software que se conecta a cuentas que pertenecen a otros usuarios de Make Agent Fast. Utiliza Authorization Code con PKCE (S256) y no emite ni requiere un client secret. El client ID es público; los códigos de autorización, los tokens de acceso, los tokens de actualización y el verificador PKCE son información sensible.

1. Registra la aplicación#

Abre Panel → Ajustes → Desarrollador → Aplicaciones OAuth. Añade:

• Un nombre de aplicación de entre 2 y 100 caracteres.
• Entre 1 y 10 URL de redirección exactas.
• Los permisos máximos que tu aplicación puede solicitar.

Las URL de redirección en producción deben usar HTTPS y no pueden contener credenciales ni fragmentos. El URI completo debe coincidir con un valor registrado durante la autorización y el intercambio del token. Las aplicaciones recién enviadas tienen el estado pending; la autorización solo funciona después de que la aplicación se revise y se marque como approved.

El propietario de la plataforma revisa los client ID pendientes con el flujo auditado oauth:review. Conserva el client ID que se muestra tras el envío; su estado es visible en la página de Desarrollador, y las aplicaciones rechazadas incluyen la decisión de revisión antes de poder volver a enviarse.

2. Genera los valores PKCE#

Genera un verificador nuevo para cada intento de autorización y guárdalo en la misma sesión protegida y de corta duración que state.

import { createHash, randomBytes } from "node:crypto";

const verifier = randomBytes(48).toString("base64url");
const challenge = createHash("sha256").update(verifier).digest("base64url");
const state = randomBytes(24).toString("base64url");

El verificador debe contener entre 43 y 128 caracteres PKCE seguros para URL. Solo se acepta code_challenge_method=S256.

3. Redirige al usuario para que dé su consentimiento#

https://makeagent.fast/oauth/authorize
  ?client_id=maf_app_...
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fcallback
  &response_type=code
  &scope=sites%3Aread%20leads%3Aread
  &state=RANDOM_STATE
  &code_challenge=PKCE_CHALLENGE
  &code_challenge_method=S256

El usuario inicia sesión, revisa los permisos solicitados y permite o deniega el acceso. Si lo permite, Make Agent Fast redirige al URI registrado exacto con code y el state original. Si lo deniega, envía error=access_denied y el state original cuando se haya proporcionado uno.

Rechaza el callback si state no coincide exactamente con el valor almacenado para esa sesión del navegador.

4. Intercambia el código de autorización#

El código de autorización caduca a los 10 minutos y solo puede usarse una vez.

curl --fail-with-body https://makeagent.fast/api/oauth/token \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "client_id=maf_app_..." \
  --data-urlencode "code=$AUTHORIZATION_CODE" \
  --data-urlencode "redirect_uri=https://app.example.com/oauth/callback" \
  --data-urlencode "code_verifier=$PKCE_VERIFIER"

{
  "access_token": "maf_live_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "maf_refresh_...",
  "scope": "sites:read leads:read"
}

El token de acceso dura una hora. El token de actualización dura hasta 90 días, salvo que se rote o se revoque antes.

5. Rota el token de actualización#

Cada actualización correcta revoca tanto el token de actualización enviado como su token de acceso anterior, y devuelve un nuevo par. Guarda el nuevo par de forma atómica antes de descartar el estado de la respuesta anterior.

curl --fail-with-body https://makeagent.fast/api/oauth/token \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "client_id=maf_app_..." \
  --data-urlencode "refresh_token=$REFRESH_TOKEN"

Reutilizar un código de autorización o un token de actualización ya rotado devuelve invalid_grant. El endpoint de tokens de OAuth devuelve respuestas de estilo OAuth { "error", "error_description" } en lugar del envoltorio de errores de la API pública, y permite 30 solicitudes de token por dirección IP del solicitante por minuto.

Nunca autentiques solicitudes de gestión en código de navegador#

No incluyas una clave de API secreta, un token de acceso ni un token de actualización en componentes cliente de React, JavaScript estático, web móvil, Webflow, Framer, Wix ni Shopify Liquid. Usa tu backend autenticado. La inserción pública del sitio web utiliza un slug de sitio no secreto y una lista de orígenes permitidos, no credenciales de la API de gestión.

Consulta Credenciales y tokens, Permisos y errores y Guía de inicio rápido de la API.