Saltar al contenido principal
Las Restricciones de claves te permiten limitar una sola clave de API a un conjunto definido de formatos de salida y endpoints. Los límites se aplican del lado del servidor durante la autenticación, por lo que una solicitud hecha con una clave restringida no puede eludirlos pasando parámetros distintos: no existe ninguna anulación a nivel de solicitud. Esto está diseñado para entornos en los que una clave se entrega a un agente automatizado o a un cliente no confiable y quieres una garantía estricta sobre lo que puede hacer; por ejemplo, permitir solo salida en Markdown para que una clave nunca pueda utilizarse para extraer raw HTML o scripts.
Las Restricciones de claves son una función empresarial y se habilitan por organización. Ponte en contacto con el equipo de cuenta de Firecrawl para habilitarlas en tu cuenta.

​
Lo que puedes restringir

Cada clave tiene dos listas de permitido independientes:
  • Formatos permitidos — los formatos de salida que la clave puede solicitar (p. ej., markdown). Cuando se configura, la clave solo puede solicitar formatos de la lista.
  • Endpoints permitidos — los grupos de endpoints que la clave puede invocar (p. ej., scrape, crawl). Cuando se configura, la clave solo puede invocar endpoints de esos grupos.
Cada lista se aplica solo cuando no está vacía. Una lista vacía significa “sin restricción” para esa dimensión, así que una clave con ambas listas vacías se comporta exactamente igual que una clave normal. Esto también significa que una clave nunca puede quedar bloqueada por una configuración vacía.

​
Configurar una clave

Los administradores del equipo configuran las restricciones desde la página de API Keys en el dashboard:
  1. Abre el menú ⋯ de la clave que quieres restringir y selecciona Restrictions.
  2. Selecciona los formatos y/o endpoints permitidos. Si no seleccionas nada en una sección, esa dimensión queda sin restricciones.
  3. Guarda. Aparecerá una insignia de Restricted en la clave y los cambios se aplicarán en aproximadamente un minuto.
Solo los administradores del equipo pueden ver o cambiar las restricciones.

​
Restricciones de formatos

Cuando una clave tiene una lista de formatos permitidos, todos los endpoints que generan scraping la aplican: /v2/scrape, /v2/batch/scrape, /v2/crawl (mediante scrapeOptions) y /v2/search (mediante scrapeOptions), además de sus equivalentes en v1. Se rechaza cualquier solicitud que pida un formato que no esté en la lista: 
{
  "success": false,
  "error": "Request blocked: this API key is restricted to the following formats: markdown. Requested formats not allowed: rawHtml. Team admins can manage key restrictions at https://www.firecrawl.dev/app/api-keys"
}

​
Acciones que devuelven contenido

Algunas acciones devuelven el contenido de la página directamente, en lugar de hacerlo a través del campo formats: screenshot, scrape, executeJavascript y pdf. En una clave con formatos restringidos, se tratan como su formato equivalente:
  • La acción screenshot solo se permite si screenshot está en la lista de formatos permitidos.
  • Las acciones scrape, executeJavascript y pdf no tienen un formato equivalente y siempre se rechazan en una clave con formatos restringidos.
Las acciones solo de interacción (wait, click, write, press, scroll) no se ven afectadas.

​
Restricciones de endpoints

Cuando una clave tiene una lista de endpoints permitidos, solo puede llamar a los endpoints de esos grupos. Las solicitudes a cualquier otro endpoint se rechazan durante la autenticación con un 403: 
{
  "success": false,
  "error": "Request blocked: this API key is restricted to the following endpoints: scrape. Team admins can manage key restrictions at https://www.firecrawl.dev/app/api-keys"
}
Grupos de endpoints disponibles: scrape, batch-scrape, crawl, map, search, extract, agent, parse, browser, monitor, research, llmstxt, deep-research, fireclaw. Algunas reglas hacen que la lista de permitido sea práctica:
  • El estado y la cancelación de un trabajo comparten el grupo de su tipo de trabajo. Por ejemplo, si crawl está permitido, GET /v2/crawl/{id} (estado), el endpoint de errores de crawl y la cancelación también lo están; no hace falta listarlos por separado.
  • Los endpoints de cuenta y metadatos siempre son accesibles (por ejemplo, /v2/team/*, /v2/concurrency-check), por lo que la gestión interna del SDK sigue funcionando independientemente de la lista de permitido.
  • Los endpoints que hacen scraping internamente están controlados por su propio grupo. extract y agent obtienen páginas como parte de su trabajo, por lo que requieren extract / agent en la lista de permitido; permitir solo scrape no les da acceso.

​
API v0 heredada

La API heredada v0 es anterior a estos controles, por lo que una clave con cualquier restricción configurada no puede usarla y recibirá un 403. Usa la API v2 en su lugar.

​
Referencia de errores

EstadoCuándo
403Un formato solicitado no figura en la lista de formatos permitidos de la clave.
403Se usa una acción que devuelve contenido con una clave restringida por formato.
403Un endpoint no figura en la lista de endpoints permitidos de la clave.
403Una clave restringida invoca la API heredada v0.
500No se pudo verificar la configuración de restricciones. Las solicitudes fallan de forma restrictiva (se rechazan) en lugar de omitir la restricción. Vuelve a intentarlo en breve.

​
Notas

  • Las restricciones se aplican por clave, así que puedes entregar una clave con restricciones a un agente mientras mantienes una clave sin restricciones para uso interactivo.
  • Los cambios se propagan a la API en aproximadamente un minuto. No hay forma de deshabilitar su cumplimiento desde una solicitud.
  • Las restricciones de clave son independientes de las restricciones de IP; una clave puede tener ambas.