Referencia de la API

Autenticación

Cómo crear y usar claves API para autenticarte con la API de FloopFloop.

Última actualización: 20 de mayo de 2026

Autenticación mediante clave de API

Todas las solicitudes a la API deben incluir tu clave de API en el encabezado Authorizationusando el esquema de token Bearer:

Authorization: Bearer flp_your_api_key_here

Crear claves de API

Ve a Cuenta → Claves de API en tu panel de FloopFloop para crear y gestionar claves de API.

Cada cuenta puede tener hasta 5 claves de API activas
Las claves se muestran solo una vez al crearlas — guárdalas de forma segura
Las claves se pueden revocar en cualquier momento desde el panel
Todas las claves comienzan con el prefijo flp_

Seguridad de las claves

Nunca compartas tus claves de API ni las incluyas en el control de versiones
Usa variables de entorno para almacenar las claves en tus aplicaciones
Rota las claves regularmente y revoca las que no estés usando
Cada clave tiene su propio cubo de límite de tasa

Límites de tasa

Los endpoints de la API tienen los siguientes límites de tasa por clave de API:

Operation	Limit	Window
Operaciones de lectura (GET)	120 requests	1 minute
Operaciones de escritura (POST/PATCH/DELETE)	30 requests	1 minute
Deploy/Rollback	5 requests	1 hour
Creación de proyecto / Clone	10 requests	1 hour

La información de límite de tasa se incluye en los encabezados de respuesta:X-RateLimit-Remaining y X-RateLimit-Reset.

Verificar autenticación

GET /api/v1/user/me

Usa este endpoint para confirmar que tu clave de API es válida. Devuelve el perfil del usuario autenticado y es la llamada estándar de “prueba de autenticación” que usan todos los SDK oficiales y floop whoami en la CLI.

curl https://floopfloop.com/api/v1/user/me \
  -H "Authorization: Bearer flp_your_api_key_here"

Respuesta (200):

{
  "data": {
    "id": "user_abc123",
    "email": "you@example.com",
    "name": "Your Name",
    "role": "user",
    "source": "api_key"
  }
}

role — "user" para cuentas normales, "admin" para el personal de la plataforma.
source — cómo se autenticó la solicitud. "api_key" para credenciales programáticas, "cli_token" para el flujo de CLI autorizado por dispositivo.

Un 401 UNAUTHORIZED aquí significa que la clave falta, fue revocada o tiene un formato incorrecto. Un 403 FORBIDDEN significa que la cuenta existe pero carece del plan Business que controla el acceso a la API (consulta Requisitos en la descripción general de la API).

Gestión programática de claves de API

La mayoría de los usuarios crea las claves desde el panel, pero la misma funcionalidad está disponible a través de la API para escenarios de orquestación — rotar una clave desde un trabajo de CI, listar claves para auditar el uso, o revocar una clave filtrada sin pasar por la interfaz de usuario. Esto es lo que hace floop keys list/create/remove en la CLI.

Listar claves de API

GET /api/v1/api-keys

Devuelve los metadatos de cada clave activa (no revocada) en la cuenta. El material de clave en texto plano nunca se devuelve — solo el keyPrefix (los primeros 8 caracteres hexadecimales de la clave, con el prefijo flp_).

{
  "data": {
    "keys": [
      {
        "id": "key_abc",
        "name": "ci-deploy",
        "keyPrefix": "flp_a1b2c3d4",
        "scopes": null,
        "lastUsedAt": "2026-04-24T18:30:00Z",
        "createdAt": "2026-04-01T12:00:00Z"
      }
    ]
  }
}

Crear clave de API

POST /api/v1/api-keys

{
  "name": "ci-deploy"    // required, 1-100 chars
}

Respuesta (201):

{
  "data": {
    "id": "key_xyz",
    "rawKey": "flp_a1b2c3d4…full-40-hex…",
    "keyPrefix": "flp_a1b2c3d4"
  }
}

El rawKey se muestra solo una vez— las lecturas posteriores devuelven únicamente el keyPrefix. Guárdalo de inmediato. Cada cuenta tiene un límite de 5 claves activas; si alcanzas el límite, la solicitud devuelve409 LIMIT_EXCEEDED— revoca una clave en desuso primero.

Para crear una clave se requiere el plan Business. Una solicitud de una cuenta sin Business devuelve 403 FORBIDDEN con el mensaje“Creating API keys requires the Business plan”. Los administradores de la plataforma omiten esta restricción.

Revocar clave de API

DELETE /api/v1/api-keys/{keyId}

Pasa el idde la clave (p. ej.key_xyz) como parámetro de ruta. La clave se invalida de inmediato — las solicitudes en tránsito que ya estén en un worker pueden completarse, pero ninguna solicitud nueva se autenticará.

Respuesta (200):

{ "data": { "success": true } }

La auto-revocación está bloqueada. Llamar a DELETE con la misma clave que realiza la solicitud devuelve400 VALIDATION_ERROR— esto evita que la CLI se desconecte a sí misma a mitad de una llamada. Usa una clave diferente o revoca desde el panel.
Las claves desconocidas o ya revocadas devuelven404 NOT_FOUND.

Los SDK oficiales aceptan tanto un id como un nombre de clave en sus helpers apiKeys.remove(), resolviendo el nombre → id del lado del cliente mediante una llamada de listado. La API en sí solo acepta el id.

Una clave revocada no puede restaurarse; crea una nueva para reemplazarla. La revocación queda registrada en el registro de auditoría que aparece en Cuenta → Claves de API.

AnteriorVisión General de la API SiguienteProyectos