> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Lectura y escritura del valor

> Por qué el valor tiene su propio punto final y cómo se acumulan las versiones detrás de él.

<a id="the-value-is-a-separate-endpoint" />

## El valor es un extremo separado

Describir un secreto y leerlo son operaciones diferentes con permisos diferentes.

<Columns cols={2}>
  <Card title="GET /v1/secrets/{id}" icon="file-text">
    Nombre, descripción, etiquetas, número de versión actual, clave KMS a la que está vinculada, estado de eliminación. **Nunca el valor.** Protegido por `secrets:DescribeSecret`.
  </Card>

  <Card title="GET /v1/secrets/{id}/value" icon="eye">
    El texto descifrado, codificado en base64. Protegido por el separado, más estrecho `secrets:GetSecretValue`.
  </Card>
</Columns>

Esta división es el punto del servicio. Una herramienta de implementación, un panel de control o un trabajo de inventario pueden recibir `secrets:DescribeSecret` en todo y aún así no ser capaces de leer un solo valor.

<Note>
  **Cada lectura de texto sin formato se registra, con éxito o no.** Una lectura denegada, una prueba para un id que el llamador no posee, y un descifrado que falló, todos se escriben en el rastro de auditoría con el código de error que los detuvo — ese conjunto es exactamente lo que una revisión está buscando, y sería invisible si solo se registraran los éxitos.
</Note>

Añada `?version=N` para leer una versión específica en lugar de la actual.

<Note>
  El botón **Reveal** de la consola, en cada fila de la pestaña **Versions** de un secreto, llama a este extremo. Es la misma operación con el mismo permiso y el mismo registro de auditoría: abrir un secreto en un navegador no es una forma más silenciosa de leerlo.
</Note>

<a id="versions" />

## Versiones

<Tabs>
  <Tab title="Console">
    Abra el secreto de **Secrets** y elija **Put New Value**. El diálogo **Put
    new value** toma el **New value**; **Store new version** lo escribe y se convierte en actual.

    Cada versión permanece en la lista de la pestaña **Versions**, con la más reciente marcada como **Current**.
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    POST /v1/secrets/{secret_id}/value
    { "value": "bmV3LXNlY3JldC12YWx1ZQ==" }
    ```
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    basaltic secrets set-value <secret-id> --value "$(base64 -w0 < new-value.txt)"
    ```

    Leer el valor actual es `basaltic secrets get-value <secret-id>`, con `--version` para uno más antiguo.
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    v, err := secrets.New(cfg).PutSecretValue(ctx, secretID, &secrets.PutSecretValueRequest{
        Value: []byte("new-secret-value"),
    })
    ```

    `v.Version` es el número que acaba de asignarse, que es lo que se registra si necesita volver al anterior.
  </Tab>
</Tabs>

Cada llamada asigna el siguiente número de versión y la hace actual; la versión anterior deja de ser actual pero permanece legible por `?version=` explícito. Eso es lo que hace que la rotación sea segura: publicas el nuevo valor, dejas que los consumidores lo recojan y aún tienes el antiguo para volver a usar.

`GET /v1/secrets/{secret_id}/versions` muestra los metadatos de la versión, la más alta primero. Cada entrada lleva `created_by`, identificando al autor que la escribió. Los usuarios se registran como `crn:iam:::user/<id>`, las cuentas de servicio por su UUID, y las sesiones de rol asumido como `crn:iam:::assumed-role/<id>`.

<Note>
  Los metadatos de versión nunca incluyen texto cifrado. `GET .../value` es la única ruta que produce texto plano, y es la única que necesita `secrets:GetSecretValue`.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.