API Reference

The KeyEnv API is a RESTful HTTP API that provides programmatic access to manage projects, environments, secrets, teams, and service tokens.

Base URL

https://api.keyenv.dev

Authentication

The API supports two authentication methods:

Bearer Token (JWT)

For web app and CLI authentication using Clerk-issued JWTs:

Authorization: Bearer <jwt-token>

Service Token

For CI/CD and programmatic access, use service tokens (prefixed with env_):

Authorization: Bearer env_<token>

Service tokens have scoped access to specific projects and environments with read and/or write permissions.

Rate Limiting

API requests are rate limited to 60 requests per minute per user/token.

Rate limit headers are included in responses:

Error Handling

All errors follow a consistent format:

{
  "error": "Human-readable error message"
}

Common HTTP status codes:

OpenAPI Specification

The complete OpenAPI specification is published alongside these docs:

• YAML: https://keyenv.dev/openapi.yaml
• JSON: https://keyenv.dev/openapi.json

Import either file into Swagger Editor, Postman, Insomnia, or an AI agent to explore the API programmatically.

Key Endpoints

Health Check

GET /health

Returns API health status. No authentication required.

Projects

Environments

Secrets

Service Tokens

Permissions

Teams

Audit Logs

Requires team admin role. Regular members receive 403 Forbidden.

Additional Endpoints

The API also includes endpoints for:

• Billing & Usage: /api/v1/teams/{id}/usage, /api/v1/teams/{id}/billing - Team usage metrics and billing information
• Team Invitations: /api/v1/teams/{id}/invitations - Manage pending team invitations
• Account Management: /api/v1/account, /api/v1/account/data-export - Account settings and data export
• Secret Rotations: /api/v1/rotations/ - Configure automatic secret rotation
• CLI Authentication: /api/v1/auth/cli/ - Device authorization flow for CLI login

Refer to the OpenAPI specification for complete endpoint documentation.

Example: List Secrets

curl -X GET "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/production/secrets" \
  -H "Authorization: Bearer env_your_token_here"

Response:

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "key": "DATABASE_URL",
      "value": "postgres://...",
      "version": 3,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:45:00Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "key": "API_KEY",
      "value": "sk_live_...",
      "version": 1,
      "inherited_from": "development",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Example: Create a Secret

curl -X POST "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/production/secrets" \
  -H "Authorization: Bearer env_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "NEW_SECRET",
    "value": "secret_value_here"
  }'

Response:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "key": "NEW_SECRET",
    "version": 1,
    "created_at": "2024-01-21T09:00:00Z",
    "updated_at": "2024-01-21T09:00:00Z"
  }
}

Example: Export Secrets

The export endpoint returns secrets in JSON format:

curl -X GET "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/production/secrets/export" \
  -H "Authorization: Bearer env_your_token_here"

Response:

{
  "data": [
    {
      "key": "DATABASE_URL",
      "value": "postgres://user:pass@localhost:5432/db"
    },
    {
      "key": "API_KEY",
      "value": "sk_live_abc123"
    },
    {
      "key": "REDIS_URL",
      "value": "redis://localhost:6379",
      "inherited_from": "development"
    }
  ]
}

The inherited_from field is present when a secret is inherited from a parent environment.

External Secrets Operator (ESO)

KeyEnv provides ESO-compatible webhook endpoints for Kubernetes integration:

See the Kubernetes ESO Integration Guide for setup instructions.

SDKs

For easier integration, use our official SDKs:

• Node.js SDK
• Python SDK
• Go SDK
• Rust SDK

The SDKs handle authentication, error handling, and provide type-safe interfaces to the API.