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://criptenv-api.77mdevseven.tech/api/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

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

Resposta de Sucesso (Lista)

200 OK — Lista paginada

[
  { "id": "proj_k8j2m4n6", "name": "projeto-a" },
  { "id": "proj_m2n4p6q8", "name": "projeto-b" }
]

Resposta de Erro

Erro padrão

{
  "detail": "O campo 'name' é obrigatório."
}

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 (pública)	`100 req`	por minuto
API Key	`1000 req`	por minuto
CI Token	`200 req`	por minuto
Auth (IP)	`5 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://criptenv-api.77mdevseven.tech/api/v1/projects?page=2&per_page=10" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

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.