Autenticación y API keys
Crear una key
- Andá a Configuración → API Keys (necesitás plan pago activo).
- 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) |
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 |
| 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.