Referência REST

Base URL: https://api.ciphervault.com.br/v1

Todas as requisições requerem Authorization: Bearer <token> (ver Autenticação). Conteúdo é JSON UTF-8. Datas em ISO 8601 UTC.

Vaults

GET /vaults

Lista vaults visíveis ao token.

{
  "vaults": [
    {
      "id": "vault_01HXYZ...",
      "name": "producao",
      "environment": "production",
      "secrets_count": 1247,
      "created_at": "2025-01-15T10:00:00Z"
    }
  ],
  "total": 4
}

POST /vaults

{
  "name": "staging-billing",
  "description": "Cofre de billing — staging",
  "environment": "staging",
  "encryption": {
    "algorithm": "AES-256-GCM",
    "key_source": "ciphervault",
    "rotation_days": 90
  }
}

GET /vaults/{name}

Detalhes do vault, incluindo configuração de criptografia, policies anexadas e contagem de secrets.

PATCH /vaults/{name}

Atualiza descrição, tags, configurações de auditoria. Nome é imutável.

DELETE /vaults/{name}

Soft delete com retenção de 30 dias (configurável). Requer aprovação multi-nível em produção.

Secrets

GET /vaults/{vault}/secrets

Lista paths. Não retorna valores — use /secrets/{path}.

Parâmetros: prefix, tags, type, limit (default 100, max 1000), cursor.

POST /vaults/{vault}/secrets

{
  "path": "api/stripe/secret_key",
  "type": "api_key",
  "value": "sk_live_...",
  "metadata": {
    "description": "Stripe billing key",
    "tags": ["stripe", "production"],
    "owner": "billing-team@acme.com.br"
  }
}

GET /vaults/{vault}/secrets/{path}

Retorna o secret descriptografado. Parâmetro opcional version (int) — sem ele, retorna a versão atual.

{
  "path": "api/stripe/secret_key",
  "type": "api_key",
  "value": "sk_live_...",
  "version": 7,
  "created_at": "2026-04-15T13:00:00Z",
  "rotated_at": "2026-04-15T13:00:00Z",
  "next_rotation": "2026-07-14T13:00:00Z",
  "metadata": { "..." }
}

PUT /vaults/{vault}/secrets/{path}

Atualiza valor e/ou metadados. Cria nova versão.

DELETE /vaults/{vault}/secrets/{path}

Soft delete. Versões antigas permanecem por retenção do plano.

GET /vaults/{vault}/secrets/{path}/versions

Lista versões com timestamp e autor de cada mudança.

POST /vaults/{vault}/secrets/{path}/rotate

Aciona rotação imediata.

{ "reason": "Suspeita de vazamento — SEC-1234" }

POST /vaults/{vault}/secrets/{path}/rollback

{ "to_version": 5, "reason": "Rotação v6 quebrou app X" }

GET /vaults/{vault}/aggregate?prefix=api/stripe

Path aggregator — retorna múltiplos secrets em uma chamada, respeitando policies.

Policies

POST /policies

{
  "name": "billing-readers",
  "document": { "version": "2025-01-01", "statement": [ ] }
}

POST /policies/{name}/attach

{ "principal": { "group": "billing-team" } }

POST /policies/simulate

Avalia uma policy contra um contexto sem aplicar — ver exemplo.

AppConnections

POST /app-connections

{
  "name": "billing-api",
  "vault": "producao",
  "allowed_paths": ["api/stripe/*", "db/postgres/billing-master"],
  "ip_allowlist": ["10.0.0.0/8"],
  "mtls_required": true
}

Retorna client_id, client_secret (única exibição), e CSR a assinar com a CA do CipherVault.

POST /app-connections/{id}/rotate

Rotaciona client_secret e/ou certificado.

Auditoria

GET /audit

Filtros: vault, actor, action, resource, from, to, decision, cursor.

curl "https://api.ciphervault.com.br/v1/audit?vault=producao&action=secrets:read&from=2026-04-01T00:00:00Z"

POST /audit/exporters

Configura export para SIEM — ver Auditoria.

Erros

Todos os erros seguem o formato:

{
  "error": {
    "code": "INSUFFICIENT_PRIVILEGE",
    "message": "Token não tem permissão secrets:read em vault/producao/api/stripe/*",
    "request_id": "req_01HXYZ..."
  }
}

HTTP status:

Status	Significado
200	Sucesso
201	Criado
400	Request inválido
401	Token inválido/expirado
403	Sem permissão
404	Recurso não encontrado
409	Conflito (rotação em curso, versão já existe)
422	Validação falhou
429	Rate limit
5xx	Erro do servidor

Versionamento da API

A API é versionada na URL (/v1). Mudanças não compatíveis vão para /v2. Deprecações são anunciadas no changelog com pelo menos 6 meses de antecedência.