Secret

Un Secret es un valor guardado una vez en el workspace y referenciado por nombre desde un paso de workflow del agente, como ${{secrets.KEY}}.

Existe para que un workflow pueda autenticarse contra sus sistemas sin que la credencial aparezca en el prompt del agente, en su respuesta ni en el registro de la petición que la usó.

Para qué sirve

• Mantener las credenciales fuera del contexto del modelo: el agente escribe la referencia, nunca el valor.
• Rotar una credencial en un único lugar, sin cambiar ningún agente.
• Mantener el valor fuera de todo lo que se persiste — la petición guardada en cada paso del workflow se escribe con todo valor de secret reemplazado por [REDACTED].

El valor es de solo escritura

Ningún endpoint, en ninguna superficie, devuelve el valor de un secret. Ni la API, ni las herramientas MCP, ni el back office de Kobana. Se guarda cifrado (AES-256-GCM, vinculado a la fila) y solo lo lee el ejecutor de workflows en el momento de construir la petición saliente.

Si pierde el valor, reemplácelo — no hay forma de leerlo de vuelta.

Schema

Campo	Tipo	Descripción
id	UUID	Id interno.
workspace_id	UUID	Workspace propietario.
key	string	El identificador que un workflow escribe dentro de ${{secrets.KEY}}. Cumple ^[A-Z][A-Z0-9_]{0,62}$ — mayúsculas, dígitos y guiones bajos, empezando por letra.
notes	string | null	Texto libre que recuerda para qué sirve el valor.
last_used_at	datetime | null	Última vez que un paso de workflow interpoló realmente este secret. null hasta el primer uso.
created_at / updated_at	datetime

value se acepta al escribir y nunca se devuelve al leer.

Nomenclatura

La gramática es estrecha a propósito: ${{secrets.A.B}} no significa nada, así que una clave con punto no podría referenciarse. Use FINANCE_TOKEN, ERP_BASIC_AUTH, NFE_API_KEY.

Endpoints

Método	Ruta	Notas
GET	/v1/secrets	Lista. Paginación por keyset, filtrable por key.
POST	/v1/secrets	Crea. Una key duplicada en el workspace da 409 conflict.
PUT	/v1/secrets	Upsert emparejado por key — el camino de la rotación, sin buscar el id.
GET	/v1/secrets/{id}	Lee uno (sin el valor).
PATCH	/v1/secrets/{id}	Reemplaza value y/o notes. key es inmutable.
DELETE	/v1/secrets/{id}	Borrado lógico.

Scopes: inbox/secrets para leer, más el verbo global write (o inbox/secrets:write) para modificar.

Por qué key no se puede renombrar

Cada workflow referencia la clave por su nombre. Un renombrado seguiría devolviendo 200 mientras rompe en silencio cada paso que usaba el nombre anterior en su próxima ejecución. Borre el secret y cree el nuevo, ajustando el prompt del agente en el mismo cambio.

Borrado

El borrado es lógico, como en todos los recursos. Desde la siguiente ejecución, un paso que referencia la clave falla con secret \KEY` is not defined in this workspace**antes** de enviar cualquier petición — ese paso falla ahí en vez de llamar a su sistema sin autenticación, y los pasos que lo referencian quedanskipped`.

Ejemplo

{
  "id": "f1e2d3c4-b5a6-4978-8899-aabbccddeeff",
  "workspace_id": "a8b2c1d4-9e7f-4a3b-8c5d-1f2e3a4b5c6d",
  "key": "FINANCE_TOKEN",
  "notes": "Cuenta de servicio del ERP — rota cada 90 días",
  "last_used_at": "2026-09-08T14:22:03.118Z",
  "created_at": "2026-06-01T09:14:00.000Z",
  "updated_at": "2026-09-01T09:14:00.000Z"
}