# Rotations

Automated credential rotation for database secrets

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

Automated credential rotation for database secrets

## List rotations

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

Lists all rotation configurations for an environment

**Operation ID:** `listRotations` &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 rotations | `RotationConfigListResponse` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |

### Response body (`200`)

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

### Example

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

## Create rotation

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

Creates a new automated credential rotation configuration

**Operation ID:** `createRotation` &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 |
| --- | --- | --- | --- |
| `name` | `string` | yes |  |
| `integration_type` | `enum (postgresql, mysql)` | yes |  |
| `connection_method` | `enum (direct, proxied)` | yes |  |
| `connection` | `object` | yes |  |
| `proxy` | `object` | no |  |
| `rotation_interval_days` | `integer` | yes |  |
| `permission_level` | `string` | no |  |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `201` | Rotation created | `RotationConfigResponse` |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |

### Response body (`201`)

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` |  |
| `environment_id` | `string (uuid)` |  |
| `name` | `string` |  |
| `integration_type` | `enum (postgresql, mysql)` |  |
| `rotation_interval_days` | `integer` |  |
| `connection_method` | `enum (direct, proxied)` |  |
| `status` | `enum (active, paused, disabled, error)` |  |
| `last_rotation_at` | `string (date-time)` |  |
| `next_rotation_at` | `string (date-time)` |  |
| `error_message` | `string` |  |
| `injected_secrets` | `string[]` |  |
| `created_at` | `string (date-time)` |  |
| `updated_at` | `string (date-time)` |  |

### Example

```bash
curl -X POST "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/rotations" \
  -H "Authorization: Bearer $KEYENV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"string","integration_type":"postgresql","connection_method":"direct","connection":{"host":"string","port":0,"database":"string","admin_username":"string","admin_password":"string","ssl_mode":"string"},"proxy":{"lambda_arn":"string","region":"string","shared_secret":"string"},"rotation_interval_days":0,"permission_level":"string"}'
```

## Test connection

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

Tests database connection without saving the rotation config

**Operation ID:** `testRotationConnection` &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 |
| --- | --- | --- | --- |
| `integration_type` | `enum (postgresql, mysql)` | yes |  |
| `connection_method` | `enum (direct, proxied)` | yes |  |
| `connection` | `object` | yes |  |
| `proxy` | `object` | no |  |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | Connection test result | `object` |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |

### Response body (`200`)

| Field | Type | Description |
| --- | --- | --- |
| `success` | `boolean` |  |
| `message` | `string` |  |

### Example

```bash
curl -X POST "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/rotations/test" \
  -H "Authorization: Bearer $KEYENV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"integration_type":"postgresql","connection_method":"direct","connection":{"host":"string","port":0,"database":"string","admin_username":"string","admin_password":"string","ssl_mode":"string"},"proxy":{"lambda_arn":"string","region":"string","shared_secret":"string"}}'
```

## Get rotation

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

Returns a rotation configuration by name

**Operation ID:** `getRotation` &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") |
| `rotationName` | `string` | yes | Rotation configuration name |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | Rotation details | `RotationConfigResponse` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `404` | Resource not found | `Error` |

### Response body (`200`)

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` |  |
| `environment_id` | `string (uuid)` |  |
| `name` | `string` |  |
| `integration_type` | `enum (postgresql, mysql)` |  |
| `rotation_interval_days` | `integer` |  |
| `connection_method` | `enum (direct, proxied)` |  |
| `status` | `enum (active, paused, disabled, error)` |  |
| `last_rotation_at` | `string (date-time)` |  |
| `next_rotation_at` | `string (date-time)` |  |
| `error_message` | `string` |  |
| `injected_secrets` | `string[]` |  |
| `created_at` | `string (date-time)` |  |
| `updated_at` | `string (date-time)` |  |

### Example

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

## Update rotation

```http
PUT /api/v1/projects/{projectId}/environments/{environmentId}/rotations/{rotationName}
```

Updates rotation interval or status

**Operation ID:** `updateRotation` &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") |
| `rotationName` | `string` | yes | Rotation configuration name |

### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `rotation_interval_days` | `integer` | no |  |
| `status` | `enum (active, paused)` | no |  |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | Rotation updated | `RotationConfigResponse` |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |

### Response body (`200`)

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` |  |
| `environment_id` | `string (uuid)` |  |
| `name` | `string` |  |
| `integration_type` | `enum (postgresql, mysql)` |  |
| `rotation_interval_days` | `integer` |  |
| `connection_method` | `enum (direct, proxied)` |  |
| `status` | `enum (active, paused, disabled, error)` |  |
| `last_rotation_at` | `string (date-time)` |  |
| `next_rotation_at` | `string (date-time)` |  |
| `error_message` | `string` |  |
| `injected_secrets` | `string[]` |  |
| `created_at` | `string (date-time)` |  |
| `updated_at` | `string (date-time)` |  |

### Example

```bash
curl -X PUT "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/rotations/{rotationName}" \
  -H "Authorization: Bearer $KEYENV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"rotation_interval_days":0,"status":"active"}'
```

## Delete rotation

```http
DELETE /api/v1/projects/{projectId}/environments/{environmentId}/rotations/{rotationName}
```

Deletes a rotation configuration

**Operation ID:** `deleteRotation` &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") |
| `rotationName` | `string` | yes | Rotation configuration name |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `204` | Rotation deleted |  |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |

### Example

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

## Trigger rotation

```http
POST /api/v1/projects/{projectId}/environments/{environmentId}/rotations/{rotationName}/rotate
```

Manually triggers a credential rotation

**Operation ID:** `triggerRotation` &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") |
| `rotationName` | `string` | yes | Rotation configuration name |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | Rotation triggered | `RotationHistory` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |

### Response body (`200`)

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` |  |
| `rotation_config_id` | `string (uuid)` |  |
| `version` | `integer` |  |
| `triggered_by` | `string (uuid)` |  |
| `trigger_type` | `enum (scheduled, manual)` |  |
| `status` | `enum (success, failed, rolled_back)` |  |
| `started_at` | `string (date-time)` |  |
| `completed_at` | `string (date-time)` |  |
| `error_message` | `string` |  |

### Example

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

## Test existing rotation

```http
POST /api/v1/projects/{projectId}/environments/{environmentId}/rotations/{rotationName}/test
```

Tests database connection for an existing rotation

**Operation ID:** `testExistingRotation` &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") |
| `rotationName` | `string` | yes | Rotation configuration name |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | Test result | `object` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |

### Response body (`200`)

| Field | Type | Description |
| --- | --- | --- |
| `success` | `boolean` |  |
| `message` | `string` |  |

### Example

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

## Get rotation history

```http
GET /api/v1/projects/{projectId}/environments/{environmentId}/rotations/{rotationName}/history
```

Returns rotation execution history

**Operation ID:** `getRotationHistory` &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") |
| `rotationName` | `string` | yes | Rotation configuration name |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | Rotation history | `object[]` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |

### Response body (`200`)

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` |  |
| `rotation_config_id` | `string (uuid)` |  |
| `version` | `integer` |  |
| `triggered_by` | `string (uuid)` |  |
| `trigger_type` | `enum (scheduled, manual)` |  |
| `status` | `enum (success, failed, rolled_back)` |  |
| `started_at` | `string (date-time)` |  |
| `completed_at` | `string (date-time)` |  |
| `error_message` | `string` |  |

### Example

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

## List rotation webhooks

```http
GET /api/v1/projects/{projectId}/environments/{environmentId}/rotations/{rotationName}/webhooks
```

Lists webhooks for a rotation configuration

**Operation ID:** `listRotationWebhooks` &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") |
| `rotationName` | `string` | yes | Rotation configuration name |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | List of webhooks | `object[]` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |

### Response body (`200`)

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` |  |
| `rotation_config_id` | `string (uuid)` |  |
| `url` | `string (uri)` |  |
| `events` | `enum (rotation.started, rotation.completed, rotation.failed)[]` |  |
| `enabled` | `boolean` |  |
| `created_at` | `string (date-time)` |  |

### Example

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

## Create rotation webhook

```http
POST /api/v1/projects/{projectId}/environments/{environmentId}/rotations/{rotationName}/webhooks
```

Creates a webhook for rotation events

**Operation ID:** `createRotationWebhook` &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") |
| `rotationName` | `string` | yes | Rotation configuration name |

### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | `string (uri)` | yes |  |
| `events` | `enum (rotation.started, rotation.completed, rotation.failed)[]` | yes |  |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `201` | Webhook created | `RotationWebhook` |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |

### Response body (`201`)

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` |  |
| `rotation_config_id` | `string (uuid)` |  |
| `url` | `string (uri)` |  |
| `events` | `enum (rotation.started, rotation.completed, rotation.failed)[]` |  |
| `enabled` | `boolean` |  |
| `created_at` | `string (date-time)` |  |

### Example

```bash
curl -X POST "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/rotations/{rotationName}/webhooks" \
  -H "Authorization: Bearer $KEYENV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"string","events":["rotation.started"]}'
```

## Delete rotation webhook

```http
DELETE /api/v1/projects/{projectId}/environments/{environmentId}/rotations/{rotationName}/webhooks/{webhookId}
```

Deletes a rotation webhook

**Operation ID:** `deleteRotationWebhook` &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") |
| `rotationName` | `string` | yes | Rotation configuration name |
| `webhookId` | `string (uuid)` | yes |  |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `204` | Webhook deleted |  |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |

### Example

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