Autenticación y API keys
Crear una key
- Andá a Configuración → API Keys (necesitás plan pago activo, o acceso vigente a FIA Agéntica: ver Copiloto FIA Agéntica).
- Ponele un nombre (ej. "Claude Desktop", "n8n", "mi script").
- Elegí los permisos (scopes). Si no marcás ninguno, la key tiene acceso total a tu data.
- Opcional: poné una fecha de expiración. La key deja de funcionar sola a partir de ahí.
- Copiá la key — se muestra una sola vez. Guardala como una contraseña.
El valor tiene la forma fia_sk_…. En la base de datos solo se guarda un hash; nadie (ni nosotros) puede recuperar el valor después.
Usar la key
Mandá la key en una de estas dos cabeceras:
# Opción A
curl https://fiacopilot.com/api/v1/me -H "Authorization: Bearer fia_sk_tu_key"
# Opción B
curl https://fiacopilot.com/api/v1/me -H "X-API-Key: fia_sk_tu_key"
Scopes (permisos)
Una key sin scopes = acceso total a tu data. Si querés limitarla, elegí entre:
| Scope | Permite |
|---|---|
memory:read |
Leer memoria, procesos, cápsulas y progreso |
memory:write |
Crear items de memoria |
briefings:read |
Listar briefings y leer sus logs |
briefings:write |
Crear/editar/revocar briefings y dejar logs |
team:read |
Ver el progreso del equipo (solo sponsor/implementador) |
agentica:read |
Copiloto FIA Agéntica: tu estado en el programa, cápsulas y progreso |
agentica:write |
Copiloto FIA Agéntica: sincronizar la bitácora, marcar cápsulas y pedir ayuda |
Alumnos de FIA Agéntica sin plan pago: su key tiene sólo agentica:read y agentica:write, aunque se cree sin scopes. Si después sacan un plan, la key pasa a respetar lo que se eligió al crearla.
Una key nunca puede hacer más de lo que vos podés hacer en la app. Los scopes solo sirven para darle menos. El acceso a /team además se revalida en cada request contra tu rol — si dejás de ser sponsor, la key deja de ver el equipo aunque tenga el scope.
Expiración y revocación
- Expiración: si la key tiene fecha de expiración, al pasar esa fecha responde
401 key_expired. Es automático, no hace falta nada. - Revocación: desde la lista de keys, "Revocar". Es inmediato — la próxima llamada con esa key responde
401 key_revoked.
Rate limits
Por key, por minuto:
- Lectura (GET): 120 req/min
- Escritura (POST/PATCH): 30 req/min
Si te pasás, recibís 429 rate_limited con una cabecera Retry-After (segundos).
Códigos de error
| HTTP | error |
Significado |
|---|---|---|
| 401 | missing_api_key |
No mandaste key |
| 401 | invalid_api_key |
La key no existe |
| 401 | key_revoked |
La key fue revocada |
| 401 | key_expired |
La key venció |
| 402 | subscription_required |
El dueño de la key no tiene plan pago activo ni acceso vigente a FIA Agéntica |
| 403 | insufficient_scope |
La key no tiene el scope necesario (devuelve required) |
| 403 | not_a_team_viewer |
No sos sponsor/implementador (endpoints de equipo) |
| 404 | not_found |
El recurso no existe o no es tuyo |
| 400 | *_required, invalid_* |
Falta un campo o un valor es inválido |
| 429 | rate_limited |
Superaste el límite por minuto |
| 500 | internal_error |
Error del servidor |
Actividad
Cada llamada (incluso las que fallan) queda registrada. La ves en Configuración → API Keys, en "Actividad reciente": status, método, endpoint, key y fecha.