---
title: "Rotate the hidden-service key (the address CHANGES)"
method: POST
path: "/platform/deployments/{id}/onion/rotate"
tags: ["Platform"]
---

# Rotate the hidden-service key (the address CHANGES)

`POST /platform/deployments/{id}/onion/rotate`

## Request

- Base URL: `https://api.imprezahost.com/v1`
- URL: `https://api.imprezahost.com/v1/platform/deployments/{id}/onion/rotate`
- Auth: API key in header `X-API-Key` and API key in header `X-API-Secret`

Destructive: the agent mints a fresh key and the `.onion` address
changes permanently; the old address dies for visitors. The prior
identity is retained on the host (parked) for recovery — destroy
it later with `/onion/purge`. Requires `manage`, `confirm: true`
and `confirm_address` with the CURRENT address verbatim. Agent
announcing `onion-custody-v1`.

## Path parameters

- `id` string, required

## Request body

- object
  - `confirm` true, required
  - `confirm_address` string, required: The CURRENT .onion address, verbatim.

## Response `202`

Rotation enqueued; the new address lands on the deployment row.

## Other responses

- `400`: Confirmation missing or the address does not match.
- `401`: Invalid or missing API credentials
- `404`: Resource not found
- `409`: A rotation is already pending, or the address changed since confirmation.
- `422`: Agent does not announce onion-custody-v1.

---

[API](https://skmtc.dev/imprezahost/apis/impreza-host-public-api.md) · [All operations](https://skmtc.dev/imprezahost/apis/impreza-host-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/imprezahost/apis/impreza-host-public-api/revisions/db86511f604f?raw)