CriptEnvv2
Início

Autenticação

A API do CriptEnv suporta múltiplos métodos de autenticação para atender diferentes cenários: dashboard web, integrações de terceiros e pipelines de CI/CD.

Visão Geral

Todas as requisições autenticadas devem incluir um token válido. A API identifica automaticamente o tipo de token pelo formato:

TipoPrefixoTTLUso
Sessãocookie30 diasDashboard web
API Keycek_Permanente (revogável)Integrações, scripts
CI Tokenci_1 horaCI/CD pipelines

Sessão (Cookies)

Quando você faz login pelo dashboard web, o servidor cria um cookie HTTP-only seguro que é enviado automaticamente em todas as requisições subsequentes do navegador.

Info

O cookie de sessão é HttpOnly, Secure e usa SameSite=Lax. Ele não pode ser acessado via JavaScript, protegendo contra ataques XSS.

Fluxo de Login

Login via API
# Fazer login e receber cookie de sessão
curl -X POST "https://api.criptenv.dev/v1/auth/login" \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{
    "email": "usuario@exemplo.com",
    "password": "senha-segura-123"
  }'
Usar sessão em requisições subsequentes
# Usar o cookie salvo em requisições seguintes
curl -X GET "https://api.criptenv.dev/v1/projects" \
  -b cookies.txt
Resposta do login (200 OK)
{
  "data": {
    "user": {
      "id": "usr_a1b2c3d4",
      "email": "usuario@exemplo.com",
      "name": "João Silva"
    },
    "expires_at": "2025-02-14T10:30:00Z"
  }
}

Refresh de Sessão

A sessão é renovada automaticamente a cada requisição bem-sucedida. Se nenhuma requisição for feita por 30 dias, a sessão expira e é necessário fazer login novamente.

API Keys

API Keys são tokens permanentes (até serem revogados) com prefixo cek_. Elas são ideais para integrações de terceiros, scripts e ferramentas que precisam de acesso programático à API.

Escopos

Cada API Key pode ter escopos granulares que controlam quais operações ela pode executar:

EscopoPermissão
readLeitura de projetos, ambientes e segredos
writePush de segredos e criação de ambientes
adminGerenciamento de projetos e membros
env:productionAcesso restrito ao ambiente de produção
env:stagingAcesso restrito ao ambiente de staging

Criar uma API Key

Criar API Key via painel ou API
curl -X POST "https://api.criptenv.dev/v1/auth/api-keys" \
  -H "Authorization: Bearer sessao_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GitHub Actions Deploy",
    "scopes": ["read", "write"],
    "environment_scope": ["staging", "production"]
  }'
Resposta (201 Created)
{
  "data": {
    "id": "key_m2n4p6q8",
    "name": "GitHub Actions Deploy",
    "prefix": "cek_",
    "key": "cek_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "scopes": ["read", "write"],
    "environment_scope": ["staging", "production"],
    "created_at": "2025-01-15T10:30:00Z"
  }
}

Info

O campo key é retornado apenas na criação. Guarde-o em um local seguro. Se perder, será necessário revogar e criar uma nova chave.

Usar API Key nas requisições

Bearer token no header
curl -X GET "https://api.criptenv.dev/v1/projects" \
  -H "Authorization: Bearer cek_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

CI Tokens

CI Tokens são tokens de curta duração (1 hora) com prefixo ci_, projetados para pipelines de CI/CD. Eles são gerados sob demanda e expiram automaticamente, eliminando o risco de tokens esquecidos.

Gerar um CI Token

Gerar CI Token temporário
curl -X POST "https://api.criptenv.dev/v1/auth/ci-tokens" \
  -H "Authorization: Bearer cek_a1b2c3d4e5f6" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_k8j2m4n6",
    "scopes": ["read"],
    "environment": "production"
  }'
Resposta (201 Created)
{
  "data": {
    "token": "ci_x9y8z7w6v5u4t3s2r1q0p9o8n7m6l5k4",
    "expires_at": "2025-01-15T11:30:00Z",
    "scopes": ["read"],
    "environment": "production"
  }
}

Usar CI Token no GitHub Actions

.github/workflows/deploy.yml
name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Generate CI Token
        id: ci-token
        run: |
          TOKEN=$(curl -s -X POST "https://api.criptenv.dev/v1/auth/ci-tokens" \
            -H "Authorization: Bearer ${{ secrets.CRIPTENV_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{
              "project_id": "${{ secrets.CRIPTENV_PROJECT_ID }}",
              "scopes": ["read"],
              "environment": "production"
            }' | jq -r '.data.token')
          echo "token=$TOKEN" >> "$GITHUB_OUTPUT"

      - name: Pull secrets
        run: |
          curl -s "https://api.criptenv.dev/v1/vault/pull" \
            -H "Authorization: Bearer ${{ steps.ci-token.outputs.token }}" \
            -o .env

OAuth

O CriptEnv suporta login social via OAuth 2.0 com os seguintes provedores:

GitHub

Ideal para desenvolvedores que já usam GitHub no dia a dia.

Google

Login rápido com sua conta Google corporativa ou pessoal.

Discord

Para membros da comunidade CriptEnv no Discord.

Fluxo OAuth 2.0

1. Iniciar fluxo OAuth — redirecionar o usuário
# Redirecionar o usuário para:
https://api.criptenv.dev/v1/auth/oauth/github/authorize
  ?redirect_uri=https://app.criptenv.dev/callback
  &state=random_csrf_token
2. Trocar o código por sessão (callback)
curl -X POST "https://api.criptenv.dev/v1/auth/oauth/github/callback" \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{
    "code": "codigo_recebido_no_callback",
    "state": "random_csrf_token"
  }'
Resposta do callback (200 OK)
{
  "data": {
    "user": {
      "id": "usr_a1b2c3d4",
      "email": "usuario@exemplo.com",
      "name": "João Silva",
      "avatar_url": "https://avatars.githubusercontent.com/u/12345"
    },
    "is_new_user": false
  }
}

Info

Após o login OAuth bem-sucedido, um cookie de sessão é criado automaticamente. As requisições subsequentes usam esse cookie normalmente.

Erros de Autenticação

401 Unauthorized — Token inválido ou expirado
{
  "error": {
    "code": "unauthorized",
    "message": "Token inválido ou expirado."
  }
}
403 Forbidden — Escopo insuficiente
{
  "error": {
    "code": "forbidden",
    "message": "Esta API Key não tem permissão para escrever neste ambiente.",
    "details": {
      "required_scope": "write",
      "current_scopes": ["read"]
    }
  }
}

Boas Práticas

  • Use API Keys para integrações server-to-server com escopos mínimos necessários.
  • Use CI Tokens em pipelines para limitar a janela de exposição a 1 hora.
  • Nunca exponha API Keys no frontend ou em logs de CI.
  • Rotacione API Keys periodicamente e revogue chaves não utilizadas.
  • Use escopos de ambiente (env:production) para limitar o impacto de uma chave comprometida.