> ## 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.

# Leitura e escrita do valor

> Por que o valor tem seu próprio endpoint e como as versões se acumulam por trás dele.

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

## O valor é um endpoint separado

Descrever um segredo e lê-lo são operações diferentes com permissões diferentes.

<Columns cols={2}>
  <Card title="GET /v1/secrets/{id}" icon="file-text">
    Nome, descrição, tags, número da versão atual, chave KMS à qual está vinculada, estado de exclusão. **Nunca o valor.** Guardado por `secrets:DescribeSecret`.
  </Card>

  <Card title="GET /v1/secrets/{id}/value" icon="eye">
    O texto simples descriptografado, base64-codificado. Guardado pelo separado, mais estreito `secrets:GetSecretValue`.
  </Card>
</Columns>

Esta divisão é o ponto do serviço. Uma ferramenta de implantação, um painel ou um trabalho de inventário pode receber `secrets:DescribeSecret` em tudo e ainda ser incapaz de ler um único valor.

<Note>
  **Cada leitura de texto simples é registrada, bem-sucedida ou não.** Uma leitura negada, uma sondagem para um id que o chamador não possui, e uma descriptografia que falhou são todas escritas na trilha de auditoria com o código de erro que as parou — esse conjunto é exatamente o que uma revisão está procurando, e seria invisível se apenas os sucessos fossem registrados.
</Note>

Adicione `?version=N` para ler uma versão específica em vez da atual.

<Note>
  O botão **Reveal** do console, em cada linha da guia **Versions** de um segredo, chama esse endpoint. É a mesma operação com a mesma permissão e o mesmo registro de auditoria — abrir um segredo em um navegador não é uma maneira mais silenciosa de lê-lo.
</Note>

<a id="versions" />

## Versões

<Tabs>
  <Tab title="Console">
    Abra o segredo de **Secrets** e escolha **Put New Value**. A caixa de diálogo **Put
    new value** recebe o **New value**; **Store new version** grava-o e torna-se atual.

    Cada versão permanece listada na guia **Versions**, com a mais recente 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)"
    ```

    A leitura do valor atual é `basaltic secrets get-value <secret-id>`, com `--version` para um mais antigo.
  </Tab>

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

    `v.Version` é o número que acabou de ser alocado, que é o que gravar se você precisar voltar para o anterior.
  </Tab>
</Tabs>

Cada chamada aloca o próximo número de versão e a torna atual; a versão anterior deixa de ser atual, mas permanece legível por `?version=` explícito. Isso é o que torna a rotação segura — você publica o novo valor, deixa os consumidores pegá-lo e ainda tem o antigo para voltar.

`GET /v1/secrets/{secret_id}/versions` lista os metadados da versão, a mais alta primeiro. Cada entrada carrega `created_by`, identificando o principal que a escreveu. Os usuários são registrados como `crn:iam:::user/<id>`, as contas de serviço por seu UUID, e as sessões de função assumida como `crn:iam:::assumed-role/<id>`.

<Note>
  Os metadados de versão nunca incluem texto cifrado. `GET .../value` é a única rota que produz texto simples, e é a única que precisa de `secrets:GetSecretValue`.
</Note>


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