Secrets

Los valores que un workflow del agente referencia como ${{secrets.KEY}}. Seis herramientas.

El valor es de solo escritura. Ninguna herramienta lo devuelve — ni siquiera al cliente que acaba de escribirlo. Si la persona va a necesitar la credencial en otro lugar, muéstrasela antes de guardarla.

Vea el modelo Secret.

---

secrets_list

Lectura · scope inbox/secrets · permiso secrets.list · GET /secrets

Lista los secrets del workspace. La respuesta trae solo key, notes, last_used_at y timestamps.

Parámetro	Tipo	Descripción
cursor	string	Cursor opaco de una página anterior.
limit	integer	Tamaño de página, por defecto 25, máximo 100.
sort	string	Claves de orden, prefijo - para descendente.
key	string	Filtra por la clave.

secrets_get

Lectura · scope inbox/secrets · permiso secrets.show · GET /secrets/{id}

Obtiene un secret por id. El valor no forma parte de la respuesta.

Parámetro	Tipo	Descripción
id obligatorio	string (uuid)	Id del secret.

secrets_create

Escritura · scope inbox/secrets + write · permiso secrets.create · POST /secrets

Guarda un secret nuevo. Una key duplicada en el workspace se rechaza con 409 conflict.

Parámetro	Tipo	Descripción
key obligatorio	string	Mayúsculas, dígitos y guiones bajos, empezando por letra — lo que un paso escribe dentro de ${{secrets.KEY}}.
value obligatorio	string	Se guarda cifrado; nunca se devuelve.
notes	string | null	Para qué sirve el valor.
idempotency_key	string	Protección contra reenvío.

secrets_upsert

Escritura · scope inbox/secrets + write · permiso secrets.create · PUT /secrets

Crea el secret, o reemplaza el valor del existente con la misma key. El camino de la rotación: sin buscar el id antes.

Parámetro	Tipo	Descripción
key obligatorio	string	Clave de búsqueda del upsert.
value obligatorio	string	Reemplaza el valor guardado.
notes	string | null
idempotency_key	string	Protección contra reenvío.

secrets_update

Escritura · scope inbox/secrets + write · permiso secrets.update · PATCH /secrets/{id}

Reemplaza el valor de un secret o sus notas. key es inmutable — los workflows la referencian por nombre, así que renombrarla los rompería en silencio.

Parámetro	Tipo	Descripción
id obligatorio	string (uuid)	Id del secret.
value	string	Valor nuevo.
notes	string | null

secrets_delete

Escritura · scope inbox/secrets + write · permiso secrets.delete · DELETE /secrets/{id}

Borra lógicamente un secret. Desde la siguiente ejecución, cualquier paso que referencie su clave falla con secret not defined, antes de enviar la petición.

Parámetro	Tipo	Descripción
id obligatorio	string (uuid)	Id del secret.