API Reference

A API REST do CriptEnv permite integrar o gerenciamento de segredos em qualquer pipeline, ferramenta ou aplicação. Esta referência cobre todos os endpoints disponíveis, formatos de autenticação, resposta e tratamento de erros.

URL Base

Todos os endpoints da API são acessados a partir da seguinte URL base:

text

https://api.criptenv.dev/v1

Todas as requisições devem ser feitas sobre HTTPS. Requisições HTTP são redirecionadas automaticamente para HTTPS.

Autenticação

A API suporta três tipos de token de autenticação. Cada um é adequado para um cenário diferente:

🍪 Sessão

Cookie HTTP-only gerado pelo login. Ideal para uso no dashboard web. TTL de 30 dias.

🔑 API Key

Token com prefixo cek_ para integrações e scripts. Suporta escopos granulares por ambiente.

⚙️ CI Token

Token com prefixo ci_ para pipelines de CI/CD. TTL curto de 1 hora, ideal para builds efêmeros.

Para mais detalhes sobre cada método, consulte a documentação de autenticação.

Formato de Resposta

Todas as respostas são retornadas em JSON com o Content-Type application/json.

Resposta de Sucesso

200 OK

{
  "data": {
    "id": "proj_k8j2m4n6",
    "name": "meu-projeto",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

Resposta de Sucesso (Lista)

200 OK — Lista paginada

{
  "data": [
    { "id": "proj_k8j2m4n6", "name": "projeto-a" },
    { "id": "proj_m2n4p6q8", "name": "projeto-b" }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 42,
    "total_pages": 3
  }
}

Resposta de Erro

Erro padrão

{
  "error": {
    "code": "validation_error",
    "message": "O campo 'name' é obrigatório.",
    "details": [
      { "field": "name", "issue": "required" }
    ]
  }
}

Códigos de Status HTTP

Código	Significado
`200`	Sucesso — operação concluída
`201`	Criado — recurso criado com sucesso
`204`	Sem conteúdo — operação sem retorno (ex: DELETE)
`400`	Requisição inválida — erro de validação nos dados enviados
`401`	Não autenticado — token ausente ou inválido
`403`	Proibido — sem permissão para esta operação
`404`	Não encontrado — recurso não existe
`409`	Conflito — recurso já existe ou versão desatualizada
`422`	Não processável — dados válidos mas semanticamente incorretos
`429`	Limite excedido — muitas requisições, tente novamente mais tarde
`500`	Erro interno — erro inesperado no servidor

Rate Limiting

A API aplica limites de taxa para proteger o serviço contra abuso. Os limites variam conforme o tipo de autenticação:

Tipo de Token	Limite	Janela
Sessão	`100 req`	por minuto
API Key	`500 req`	por minuto
CI Token	`200 req`	por minuto

Os headers de rate limit são incluídos em todas as respostas:

Headers de Rate Limit

X-RateLimit-Limit: 500
X-RateLimit-Remaining: 487
X-RateLimit-Reset: 1705312800

Info

Quando o limite é excedido, a API retorna 429 Too Many Requests. O header Retry-After indica quantos segundos aguardar.

Paginação

Endpoints que retornam listas suportam paginação via query parameters:

Parâmetro	Tipo	Descrição
`page`	`integer`	Número da página (padrão: 1)
`per_page`	`integer`	Itens por página (padrão: 20, máx: 100)
`sort`	`string`	Campo para ordenação (ex: `created_at`)
`order`	`string`	Direção: `asc` ou `desc` (padrão: desc)

Exemplo de paginação

curl -X GET "https://api.criptenv.dev/v1/projects?page=2&per_page=10" \
  -H "Authorization: Bearer cek_a1b2c3d4e5f6"

Referência por Domínio

Autenticação

Detalhes sobre sessões, API Keys, CI Tokens e OAuth.

Projetos

CRUD de projetos, incluindo operações de vault e re-key.

Ambientes

Gerenciamento de ambientes dentro de um projeto.

Vault

Push, pull e versionamento de segredos criptografados.

Membros

Convites, papéis e gerenciamento de acesso a projetos.