Auth de la API: token Bearer de una clave

Autentica la API de Feedjolt con claves API enviadas como token Bearer en la cabecera Authorization. Crea, limita y revoca claves, solo servidor a servidor.

La API usa claves de workspace. Envía la clave como Authorization: Bearer <key> o como X-API-Key: <key>. Las sesiones del panel por cookie siguen funcionando sin clave.

Crear una clave

Panel -> Ajustes -> Claves API -> Nueva clave.

Configurarás:

Nombre - para tu cordura. production-zapier, local-dev-marc. No "key", "test", "asdf".
Scopes - qué puede hacer la clave (almacenado como un array JSON en la clave).

La clave completa se muestra una sola vez al generarse. Guárdala; solo guardamos un hash. Clave perdida = haz una nueva.

Formato

fjk_<random>

El prefijo fjk_ es intencional:

Fácil de detectar en tus logs (y en nuestra detección de filtraciones de git).
Fácil escribir un regex / hook de pre-commit contra él.
Te permite saber a primera vista "esta es una clave de Feedjolt, no de Stripe".

Trata la clave completa como un secreto. No pongas claves en: código del cliente, apps móviles, repos públicos, tickets de soporte, capturas.

Enviar la clave

Prefiere Bearer. X-API-Key es la misma credencial.

Authorization: Bearer fjk_abc123...

X-API-Key: fjk_abc123...

Una clave pertenece a un solo workspace. GET /api/v1/workspaces devuelve ese workspace.

Ejemplos:

curl -H "Authorization: Bearer $FEEDJOLT_KEY" \
     "https://api.feedjolt.com/api/v1/workspaces"

fetch("https://api.feedjolt.com/api/v1/workspaces", {
  headers: { Authorization: `Bearer ${process.env.FEEDJOLT_KEY}` }
});

import os, httpx
r = httpx.get(
    "https://api.feedjolt.com/api/v1/workspaces",
    headers={"Authorization": f"Bearer {os.environ['FEEDJOLT_KEY']}"}
)

Las claves llevan una lista de scopes. Los strings exactos de scope y las comprobaciones por endpoint están documentados en la referencia OpenAPI bajo la sección "security" de cada endpoint - esa es la fuente de verdad.

Al elegir scopes, parte de solo lectura y expande solo según necesites. Las llamadas sin el scope adecuado devuelven 403.

Revocar

Ajustes -> Claves API -> Revocar. Inmediato.

Si una clave se filtra:

Revócala.
Genera una clave nueva.
Actualiza tu store de secretos.
Redespliega.
Considera rotar cualquier dato que haya podido leerse.

Solo servidor a servidor

No existe un flujo de clave API para cliente. Las claves deben quedarse en servidor. Las llamadas desde el navegador deben pasar por tu backend.

Para acceso cliente sin auth (datos públicos de solo lectura), usa el widget o las URLs estándar del portal público - están indexadas y sin requisito de auth.

Estado de la suscripción

Las claves API necesitan un plan con derecho (Startup o Scale) y un estado con derecho. Filas canceladas, impagadas, incompletas o nunca pagadas devuelven 403 SUBSCRIPTION_INACTIVE en cada llamada, también en GET. past_due mantiene acceso completo 7 días después de la primera marca de renovación fallida (past_due_since); luego las lecturas siguen y las escrituras devuelven el mismo 403. El current_period_end renovado no alarga esa ventana. Los espacios compensados (comped) nunca se bloquean. Las sesiones cookie del panel quedan en solo lectura si están canceladas; no usan esta puerta de claves API.

Administración desde el panel

La gestión de miembros, las conexiones de integraciones, las claves API, la facturación y la configuración JWT requieren una sesión iniciada en el panel. Las claves API no pueden acceder a estos recursos, aunque tengan todos los permisos. Una petición que incluya tanto una clave API como una cookie del panel sigue sujeta a las restricciones de la clave API.

Usa el panel para invitar a compañeros o conectar Slack, Linear o GitHub. El acceso de la API a los recursos de feedback sigue disponible según los permisos de la clave.

Autenticación de la API