Rotations

Automated credential rotation for database secrets

List rotations

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

Lists all rotation configurations for an environment

Operation ID: listRotations · 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

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

Create rotation

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

Creates a new automated credential rotation configuration

Operation ID: createRotation · 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
`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

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

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

Tests database connection without saving the rotation config

Operation ID: testRotationConnection · 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
`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

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

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

Returns a rotation configuration by name

Operation ID: getRotation · 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

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

Update rotation

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

Updates rotation interval or status

Operation ID: updateRotation · 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

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

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

Deletes a rotation configuration

Operation ID: deleteRotation · 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

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

Trigger rotation

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

Manually triggers a credential rotation

Operation ID: triggerRotation · 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

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

Test existing rotation

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

Tests database connection for an existing rotation

Operation ID: testExistingRotation · 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

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

Get rotation history

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

Returns rotation execution history

Operation ID: getRotationHistory · 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

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

List rotation webhooks

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

Lists webhooks for a rotation configuration

Operation ID: listRotationWebhooks · 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

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

Create rotation webhook

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

Creates a webhook for rotation events

Operation ID: createRotationWebhook · 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

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

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

Deletes a rotation webhook

Operation ID: deleteRotationWebhook · 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

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

Rotations

On this page