# Secrets

Secret management (encrypted key-value pairs)

Source: https://keyenv.dev/docs/api/secrets/

Secret management (encrypted key-value pairs)

## List secrets

```http
GET /api/v1/projects/{projectId}/environments/{environmentId}/secrets
```

Returns all secrets in an environment (keys and metadata only, no values). Includes inherited secrets from parent environments.

**Operation ID:** `listSecrets` &middot; **Authentication:** `Authorization: Bearer <token>`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | List of secrets | `object` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `404` | Resource not found | `Error` |

### Response body (`200`)

| Field | Type | Description |
| --- | --- | --- |
| `secrets` | `object[]` |  |

### Example

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

## Create secret

```http
POST /api/v1/projects/{projectId}/environments/{environmentId}/secrets
```

Creates a new secret in an environment

**Operation ID:** `createSecret` &middot; **Authentication:** `Authorization: Bearer <token>`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |

### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `key` | `string` | yes | Must be uppercase letters, numbers, and underscores, starting with a letter |
| `value` | `string` | yes |  |
| `description` | `string` | no |  |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `201` | Secret created | `object` |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `409` | Resource already exists | `Error` |
| `429` | Plan limit exceeded | `LimitError` |

### Response body (`201`)

| Field | Type | Description |
| --- | --- | --- |
| `secret` | `Secret` |  |

### Example

```bash
curl -X POST "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/secrets" \
  -H "Authorization: Bearer $KEYENV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key":"DATABASE_URL","value":"string","description":"string"}'
```

## Export secrets

```http
GET /api/v1/projects/{projectId}/environments/{environmentId}/secrets/export
```

Exports all secrets with their decrypted values. Use this for CI/CD or local development.
Includes inherited secrets from parent environments.

**Note:** This endpoint logs an audit event for compliance.

**Operation ID:** `exportSecrets` &middot; **Authentication:** `Authorization: Bearer <token>`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | Secrets with values | `object` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `404` | Resource not found | `Error` |

### Response body (`200`)

| Field | Type | Description |
| --- | --- | --- |
| `secrets` | `object[]` |  |

### Example

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

## Bulk import secrets

```http
POST /api/v1/projects/{projectId}/environments/{environmentId}/secrets/bulk
```

Imports multiple secrets at once. Useful for migrating from .env files or other systems.

- Maximum 100 secrets per request
- Set `overwrite: true` to update existing secrets
- Set `overwrite: false` to skip existing secrets

**Operation ID:** `bulkImportSecrets` &middot; **Authentication:** `Authorization: Bearer <token>`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |

### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `secrets` | `object[]` | yes |  |
| `overwrite` | `boolean` | no | Whether to overwrite existing secrets |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | Import results | `BulkImportResult` |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `429` | Plan limit exceeded | `LimitError` |

### Response body (`200`)

| Field | Type | Description |
| --- | --- | --- |
| `created` | `integer` | Number of secrets created |
| `updated` | `integer` | Number of secrets updated (when overwrite=true) |
| `skipped` | `integer` | Number of secrets skipped (existing, when overwrite=false) |

### Example

```bash
curl -X POST "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/secrets/bulk" \
  -H "Authorization: Bearer $KEYENV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"secrets":[{"key":"string","value":"string","description":"string"}],"overwrite":false}'
```

## Get secret

```http
GET /api/v1/projects/{projectId}/environments/{environmentId}/secrets/{key}
```

Returns a single secret with its decrypted value

**Operation ID:** `getSecret` &middot; **Authentication:** `Authorization: Bearer <token>`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |
| `key` | `string` | yes | Secret key (uppercase letters, numbers, underscores) |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | Secret with value | `object` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `404` | Resource not found | `Error` |

### Response body (`200`)

| Field | Type | Description |
| --- | --- | --- |
| `secret` | `object` |  |

### Example

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

## Update secret

```http
PUT /api/v1/projects/{projectId}/environments/{environmentId}/secrets/{key}
```

Updates a secret's value and/or description. Previous values are preserved in history.

**Operation ID:** `updateSecret` &middot; **Authentication:** `Authorization: Bearer <token>`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |
| `key` | `string` | yes | Secret key (uppercase letters, numbers, underscores) |

### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | `string` | yes |  |
| `description` | `string` | no |  |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | Secret updated | `object` |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `404` | Resource not found | `Error` |

### Response body (`200`)

| Field | Type | Description |
| --- | --- | --- |
| `secret` | `Secret` |  |

### Example

```bash
curl -X PUT "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/secrets/{key}" \
  -H "Authorization: Bearer $KEYENV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value":"string","description":"string"}'
```

## Delete secret

```http
DELETE /api/v1/projects/{projectId}/environments/{environmentId}/secrets/{key}
```

Permanently deletes a secret

**Operation ID:** `deleteSecret` &middot; **Authentication:** `Authorization: Bearer <token>`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |
| `key` | `string` | yes | Secret key (uppercase letters, numbers, underscores) |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `204` | Secret deleted |  |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `404` | Resource not found | `Error` |

### Example

```bash
curl -X DELETE "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/secrets/{key}" \
  -H "Authorization: Bearer $KEYENV_TOKEN"
```

## Get secret history

```http
GET /api/v1/projects/{projectId}/environments/{environmentId}/secrets/{key}/history
```

Returns the version history of a secret with decrypted values

**Operation ID:** `getSecretHistory` &middot; **Authentication:** `Authorization: Bearer <token>`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |
| `key` | `string` | yes | Secret key (uppercase letters, numbers, underscores) |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | Secret history | `object` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `404` | Resource not found | `Error` |

### Response body (`200`)

| Field | Type | Description |
| --- | --- | --- |
| `history` | `object[]` |  |

### Example

```bash
curl -X GET "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/secrets/{key}/history" \
  -H "Authorization: Bearer $KEYENV_TOKEN"
```