Autenticação na API

A API REST do CipherVault aceita três métodos de autenticação. Use o que melhor se encaixa no seu cenário.

1. Personal Access Token (PAT)

Para uso humano, scripts pontuais e ferramentas internas.

Gere em Configurações → Tokens pessoais. Defina:

• Nome descritivo
• TTL (até 365 dias)
• Escopo (vaults e ações específicos)
• IP allowlist opcional

curl -H "Authorization: Bearer cv_pat_..." \
  https://api.ciphervault.com.br/v1/vaults

PATs são JWTs assinados com jti único, rastreável em audit log e revogável imediatamente.

2. OIDC Federation (recomendado para CI/CD)

Pipelines em GitHub Actions, GitLab CI, CircleCI, Jenkins e Bamboo trocam o JWT do provedor por um token efêmero do CipherVault — sem secrets estáticos.

Veja OIDC Federation para configuração completa.

# .github/workflows/deploy.yml
- uses: ciphervault/oidc-action@v1
  with:
    audience: 'https://ciphervault.com.br'
    vault: 'producao'
- run: ./deploy.sh
  env:
    DB_PASSWORD: ${{ steps.cv.outputs.db_password }}

3. AppConnection (mTLS)

Para serviços de produção (microsserviços, batch jobs). Cada AppConnection tem client_id + client_secret + certificado mTLS X.509 + IP allowlist.

curl --cert app.crt --key app.key \
  -H "X-Client-Id: app_..." \
  -H "X-Client-Secret: cs_..." \
  https://api.ciphervault.com.br/v1/vaults/producao/secrets/db/postgres/master

Os SDKs oficiais cuidam do mTLS e renovação automática.

Comparação

Método	Uso	TTL típico	Rotação	Auditoria
PAT	Humano, scripts	30–365 dias	Manual	Por jti
OIDC	CI/CD	Por job (5–60 min)	Automática	Por workflow run
AppConnection	Serviços	Permanente	Automática (cert mTLS)	Por client_id

Rate limits

Limites padrão (configuráveis por plano e por token):

• Leitura: 1.000 req/min (Starter), 10.000/min (Professional), customizado (Enterprise).
• Escrita: 100 req/min.
• Rotação: 10 req/min.
• Aggregator: 500 req/min.

Headers de resposta:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 873
X-RateLimit-Reset: 1714831200

Em caso de excesso: HTTP 429 Too Many Requests com Retry-After.

Erros

{
  "error": {
    "code": "INVALID_TOKEN",
    "message": "Token expirado ou revogado",
    "request_id": "req_01HXYZ...",
    "details": { "jti": "..." }
  }
}

Códigos comuns: INVALID_TOKEN, INSUFFICIENT_PRIVILEGE, MFA_REQUIRED, IP_NOT_ALLOWED, RATE_LIMIT_EXCEEDED, VAULT_NOT_FOUND, SECRET_NOT_FOUND, VERSION_NOT_FOUND, ROTATION_IN_PROGRESS.

Próximo passo

Referência completa de endpoints REST →