# Claves de IA

Crear claves de Router IA con tope de gasto, token visible una sola vez, límites para empresas nuevas, revocación y reactivación.

Fuente: https://ardumaker.com/docs/claves-ia/

- Categoría: Inteligencia artificial y agentes
- Estado: Disponible
- Requisitos: Ser admin de la empresa para crear, revocar o reactivar; Un medio de pago activo en la empresa; Al menos 20 EUR de saldo, y saldo suficiente para cubrir el tope pedido
- Herramientas MCP (Solo leen): `listar_claves_router_ia`, `ver_clave_router_ia`
- Herramientas MCP (Escriben o modifican): `crear_clave_router_ia`, `revocar_clave_router_ia`, `reactivar_clave_router_ia`, `crear_token_search_api`, `revocar_token_search_api`, `reactivar_token_search_api`

## ¿Qué permite hacer?

- Crear claves de [Router IA](https://ardumaker.com/docs/router-ia) con un nombre, un tope de gasto en USD y un período de reinicio del tope (`daily`, `weekly` o `monthly`).
- Revocar una clave: deja de funcionar en OpenRouter y se registra el gasto pendiente.
- Reactivar una clave revocada.
- Listar las claves y ver su uso sin exponer nunca el token.

## ¿Cuándo conviene usarlo?

- Una clave por aplicación o entorno, para separar gastos y poder cortar una sin afectar las otras.
- Cuando un token se filtró: revocarlo y crear uno nuevo.
- Para limitar cuánto puede gastar una integración por día, semana o mes.

## ¿Cómo funciona en ArduMaker?

### Crear

1. Se comprueba que quien pide sea admin de la empresa y que la empresa tenga un medio de pago activo.
2. Se comprueba el saldo: al menos 20 EUR, y que alcance para el tope pedido.
3. Si la empresa es nueva (menos de 7 días o sin un pago autorizado): como mucho 5 claves activas, tope diario de hasta 30 USD y solo reinicio diario.
4. Se crea la clave en OpenRouter. Sin `limit`, nace con un tope de 30 USD que se reinicia cada día.
5. La respuesta trae el token completo **una sola vez**. Después no se vuelve a mostrar por MCP ni en los listados.

> **PRECAUCION:** `limit` es el **tope de gasto** de la clave, no un tamaño de página. Mandar 50 crea una clave que puede gastar 50 USD por período.

### Revocar y reactivar

- Revocar sincroniza el uso (para registrar lo pendiente), deshabilita la clave en OpenRouter y la marca como eliminada. La fila no se borra.
- Reactivar la vuelve a habilitar en OpenRouter y limpia la marca de pausa por saldo.
- Una clave pausada por saldo negativo o por verificación de identidad no está revocada: se reactiva sola cuando se resuelve la causa.

Los tokens de [Search API](https://ardumaker.com/docs/search-api) siguen reglas parecidas (admin, medio de pago, 20 EUR de saldo, token visible una vez, revocar y reactivar), pero no tienen tope de gasto propio.

## ¿Qué cambia realmente?

- En OpenRouter: la clave, con un nombre que lleva la empresa y el nombre elegido.
- En ArduMaker: la clave queda asociada a un servicio de la empresa; revocarla quita ese servicio.
- En el historial de la empresa: el consumo, a medida que se sincroniza.

## Esquema

**Ciclo de vida de una clave**

```text
Creada (token visible una vez)
  ↓
Activa (gasta hasta su tope por período)
  ↓
Pausada (saldo negativo o verificación; vuelve sola)
  ↓
Revocada (deshabilitada; se puede reactivar)
```

## Resultado esperado

- `crear_clave_router_ia` devuelve `id`, `name`, `api_key` (el token) y un aviso para guardarlo ya.
- `ver_clave_router_ia` devuelve uso, tope, restante y reinicio; con permisos de admin, también el detalle de gastos.
- Una clave revocada deja de aparecer como activa y OpenRouter la rechaza.

## Errores y resolución

| Respuesta | Causa | Qué hacer |
| --- | --- | --- |
| 403 | Solo un admin de la empresa crea, revoca o reactiva | Pedirlo a un admin |
| 400 sin medio de pago | La empresa no tiene un medio de pago activo | Agregar uno |
| 400 saldo | Menos de 20 EUR, o el tope pedido supera el saldo | Recargar o pedir un tope menor |
| 400 empresa nueva | Más de 5 claves, tope diario de más de 30 USD o reinicio no diario | Se libera con más de 7 días y un pago autorizado |
| 400 ya revocada / ya activa | La clave ya estaba en ese estado | Nada que hacer |
| Error de OpenRouter | OpenRouter rechazó o no contestó | Reintentar más tarde |

> **PELIGRO:** `crear_clave_router_ia` no es idempotente por sí sola: un reintento sin la misma `idempotency_key` crea una segunda clave. Con la misma clave de idempotencia se recupera el resultado original (incluido el token) durante 24 horas.

## Relación con MCP

Sí, en los perfiles `/mcp` e `/mcp/infra`.

| Herramienta | Tipo | Notas |
| --- | --- | --- |
| `listar_claves_router_ia`, `ver_clave_router_ia` | Lectura | Nunca devuelven el token |
| `crear_clave_router_ia` | Escritura | Admin; devuelve el token una vez; acepta `idempotency_key` |
| `revocar_clave_router_ia` | Destructiva, reversible | Admin |
| `reactivar_clave_router_ia` | Escritura | Admin |
| `crear_token_search_api`, `revocar_token_search_api`, `reactivar_token_search_api` | Escritura | Tokens de Search API, mismas reglas de admin |

El token es un dato sensible en la respuesta: el agente tiene que entregárselo a su humano y no publicarlo. Referencia en [/mcp/docs](https://ardumaker.com/mcp/docs) y ejemplos en [/mcp/ia](https://ardumaker.com/mcp/ia).

## Funciones relacionadas

- [Router IA](https://ardumaker.com/docs/router-ia/)
- [Search API](https://ardumaker.com/docs/search-api/)
- [Saldo por empresa](https://ardumaker.com/docs/saldo-por-empresa/)
- [Servidor MCP](https://ardumaker.com/docs/servidor-mcp/)