Agent keys
Credenciales bound a un agente: crear, rotar con gracia y revocar.
Una agent key (ak_arg_…) autentica como un agente puntual. La identidad se
resuelve desde la propia credencial, sin pasar el label como argumento.
Propiedades
| Campo | Descripción |
|---|---|
id | Identificador de la key |
label | Nombre libre (opcional) |
prefix | Siempre ak_arg |
last_four | Últimos 4 chars (la key completa se ve una sola vez) |
status | active o revoked |
grace_until | Vigencia de una key rotada, hasta +24h |
rotated | true si fue reemplazada por otra |
last_used_at | Último uso |
La key cruda (ak_arg_<hex>) se devuelve una sola vez, al crearla. En la base
guardamos solo sha256(key) + los últimos 4 chars. No es recuperable.
Ciclo de vida
Crear
POST /api/v1/wallet/sub-wallets/{id}/keys → { key, raw } (201). raw es la
credencial completa.
Rotar (zero-downtime)
POST /api/v1/wallet/sub-wallets/{id}/keys/{keyId}/rotate emite una key nueva y deja
la vieja válida hasta grace_until (+24h). Actualizás el deploy sin cortar el servicio.
Revocar
DELETE /api/v1/wallet/sub-wallets/{id}/keys/{keyId} corta el acceso al instante,
sin gracia. El historial del agente queda intacto.
Alcance
Una sesión abierta con agent key queda scopeada a ese agente. Las tools que crean
agentes o reasignan fondos (wallet_create_agent, wallet_allocate) están prohibidas
para agent keys. Ver Autenticación.
Hoy las agent keys se aceptan en el MCP de wallet. El resolvedor
(resolveAgentKey) ya está; extenderlo a más superficies es incremental.