# API Reference

Complete REST API documentation for KeyEnv

Source: https://keyenv.dev/docs/sdks/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:

```bash
Authorization: Bearer <jwt-token>
```

### Service Token

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

```bash
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:

| Header | Description |
|--------|-------------|
| `X-RateLimit-Limit` | Maximum requests per minute |
| `X-RateLimit-Remaining` | Remaining requests in current window |
| `X-RateLimit-Reset` | Unix timestamp when the limit resets |

## Error Handling

All errors follow a consistent format:

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

Common HTTP status codes:

| Code | Description |
|------|-------------|
| 400 | Bad request - invalid input |
| 401 | Unauthorized - missing or invalid authentication |
| 403 | Forbidden - insufficient permissions |
| 404 | Resource not found |
| 409 | Conflict - resource already exists |
| 429 | Rate limit exceeded |
| 500 | Internal server error |

## OpenAPI Specification

The complete OpenAPI specification is published alongside these docs:

- **YAML**: [https://keyenv.dev/openapi.yaml](/openapi.yaml)
- **JSON**: [https://keyenv.dev/openapi.json](/openapi.json)

Import either file into [Swagger Editor](https://editor.swagger.io/), [Postman](https://www.postman.com/), [Insomnia](https://insomnia.rest/), or an AI agent to explore the API programmatically.

> **Note**
>
> The [API Reference](/docs/api) section documents every endpoint, parameter, and response schema. It is generated from this specification, so it never drifts from the running API.

## Key Endpoints

### Health Check

```bash
GET /health
```

Returns API health status. No authentication required.

### Projects

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/v1/projects` | List all projects |
| POST | `/api/v1/projects` | Create a project |
| GET | `/api/v1/projects/{id}` | Get a project |
| PATCH | `/api/v1/projects/{id}` | Update a project |
| DELETE | `/api/v1/projects/{id}` | Delete a project |

### Environments

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/v1/projects/{id}/environments` | List environments |
| POST | `/api/v1/projects/{id}/environments` | Create an environment |
| GET | `/api/v1/projects/{id}/environments/{env}` | Get an environment |
| DELETE | `/api/v1/projects/{id}/environments/{env}` | Delete an environment |

### Secrets

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/v1/projects/{id}/environments/{env}/secrets` | List secrets |
| POST | `/api/v1/projects/{id}/environments/{env}/secrets` | Create a secret |
| GET | `/api/v1/projects/{id}/environments/{env}/secrets/{key}` | Get a secret |
| PUT | `/api/v1/projects/{id}/environments/{env}/secrets/{key}` | Update a secret |
| DELETE | `/api/v1/projects/{id}/environments/{env}/secrets/{key}` | Delete a secret |
| GET | `/api/v1/projects/{id}/environments/{env}/secrets/export` | Export secrets (JSON) |
| POST | `/api/v1/projects/{id}/environments/{env}/secrets/bulk` | Bulk import |

### Service Tokens

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/v1/tokens` | List tokens |
| POST | `/api/v1/tokens` | Create a token |
| DELETE | `/api/v1/tokens/{id}` | Delete a token |
| POST | `/api/v1/tokens/{id}/rotate` | Rotate a token |

### Permissions

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/v1/projects/{id}/my-permissions` | Get my permissions |
| GET | `/api/v1/projects/{id}/environments/{env}/permissions` | List permissions |
| PUT | `/api/v1/projects/{id}/environments/{env}/permissions/{userId}` | Set permission |
| DELETE | `/api/v1/projects/{id}/environments/{env}/permissions/{userId}` | Delete permission |

### Teams

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/v1/teams` | List teams |
| POST | `/api/v1/teams` | Create a team |
| GET | `/api/v1/teams/{id}` | Get a team |
| POST | `/api/v1/teams/{id}/members` | Invite a member |
| DELETE | `/api/v1/teams/{id}/members/{userId}` | Remove a member |

### Audit Logs

Requires team admin role. Regular members receive `403 Forbidden`.

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/v1/audit` | List audit logs (admin only) |
| GET | `/api/v1/teams/{id}/audit` | List team audit logs (admin only) |

### 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](https://github.com/keyenv/keyenv/blob/main/api/openapi.yaml) for complete endpoint documentation.

## Example: List Secrets

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

Response:

```json
{
  "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

```bash
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:

```json
{
  "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:

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

Response:

```json
{
  "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:

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/v1/eso/secret` | Get single secret |
| GET | `/api/v1/eso/secrets` | Get all secrets (for dataFrom) |

See the [Kubernetes ESO Integration Guide](/docs/sdks/kubernetes-eso) for setup instructions.

## SDKs

For easier integration, use our official SDKs:

- [Node.js SDK](/docs/sdks/nodejs)
- [Python SDK](/docs/sdks/python)
- [Go SDK](/docs/sdks/go)
- [Rust SDK](/docs/sdks/rust)

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