Criando e versionando secrets

Após criar um vault, você pode armazenar secrets dele. Cada secret tem nome (path), valor criptografado, metadados, versionamento e política de acesso herdada do vault — opcionalmente sobrescrita.

Tipos de secret suportados

Tipo	Uso	Exemplo
password	Senha texto puro	DB master, admin web
api_key	Token de API	Stripe, Twilio, OpenAI
ssh_key	Chave SSH (privada + pública)	Acesso a servidores
certificate	Certificado X.509 (cert + chave)	mTLS, TLS interno
kv	Chave/valor estruturado JSON	Config de aplicação
database	Credencial gerenciada (suporta rotação)	PostgreSQL, MySQL, Oracle

Pela UI

1. Entre no vault desejado.
2. Clique em Novo secret.
3. Escolha o path hierárquico (ex.: api/stripe/secret_key).
4. Selecione o tipo e preencha o valor.
5. Adicione metadados opcionais: descrição, tags, dono, ticket relacionado.
6. Configure rotação (apenas para tipos database e api_key).
7. Salve.

A versão v1 é gerada automaticamente. Toda atualização incrementa a versão e mantém o histórico — você pode ler versões antigas (com permissão) e reverter rotações falhas.

Via API

curl -X POST https://api.ciphervault.com.br/v1/vaults/producao/secrets \
  -H "Authorization: Bearer $CIPHERVAULT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "api/stripe/secret_key",
    "type": "api_key",
    "value": "sk_live_abc123...",
    "metadata": {
      "description": "Stripe live secret key — billing",
      "owner": "billing-team@acme.com.br",
      "tags": ["stripe", "billing", "production"]
    }
  }'

Via SDK (Python)

from ciphervault import Client

client = Client(endpoint="https://api.ciphervault.com.br")  # token via env

client.secrets.create(
    vault="producao",
    path="api/stripe/secret_key",
    type="api_key",
    value="sk_live_abc123...",
    metadata={
        "description": "Stripe live secret key",
        "owner": "billing-team@acme.com.br",
    },
)

# Leitura
secret = client.secrets.get(vault="producao", path="api/stripe/secret_key")
print(secret.value)

Outros idiomas: Node.js, Java, Go, C#.

Versionamento

Cada secret mantém histórico imutável de versões. Para ler uma versão específica:

GET /v1/vaults/producao/secrets/api/stripe/secret_key?version=3

Para reverter:

POST /v1/vaults/producao/secrets/api/stripe/secret_key/rollback
{
  "to_version": 3,
  "reason": "Rotação v4 falhou em produção"
}

A retenção de versões é configurável por plano:

• Starter — 30 dias / 10 versões
• Professional — 1 ano / 100 versões
• Enterprise — ilimitado

Path aggregators

Aplicações podem buscar múltiplos secrets em uma única chamada com path aggregators — ideal para hidratar configuração de uma só vez:

GET /v1/vaults/producao/aggregate?prefix=api/stripe

{
  "api/stripe/secret_key": "sk_live_...",
  "api/stripe/webhook_secret": "whsec_..."
}

Path aggregators respeitam policies — secrets sem permissão são silenciosamente omitidos da resposta.

Boas práticas

• Use paths hierárquicos. Facilita policies e descoberta.
• Não armazene em texto plano em logs. Os SDKs já mascaram; revise seu código.
• Marque o dono. Metadado owner simplifica governance.
• Habilite rotação automática para credenciais de banco de dados e IAM.
• Tagueie por criticidade (critical, pii, pci) para compor policies condicionais.

Próximo passo

Configurar políticas de acesso (RBAC) →