---
title: "Rotate a voice agent's signing secret"
method: POST
path: "/v3/voice/agents/{id}/rotate-secret"
tags: ["Voice"]
---

# Rotate a voice agent's signing secret

`POST /v3/voice/agents/{id}/rotate-secret`

## Request

- Base URL: `https://api.sent.dm`
- URL: `https://api.sent.dm/v3/voice/agents/{id}/rotate-secret`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Generates a new `signing_secret` for the agent and returns it. The previous secret stops signing immediately, so update your agent before the next call reaches it.

With `sandbox: true` a secret is generated and returned with `202`, and nothing is written.

## Path parameters

- `id` string, required

## Headers

- `Idempotency-Key` string
- `x-profile-id` string, uuid

## Request body

- SentDmServicesEndpointsCustomerAPIv3VoiceAgentsRequestsRotateVoiceAgentSecretRequest: Base request for mutation operations (POST, PUT, PATCH) with sandbox mode support
  - `sandbox` boolean: Sandbox flag - when true, the operation is simulated without side effects Useful for testing integrations without actual execution

## Response `200`

The new secret. The old one no longer signs anything

- SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfVoiceAgentSecretResponse: Standard API response envelope for all v3 endpoints
  - `success` boolean: Indicates whether the request was successful
  - `data` SentDmServicesCommonServicesVoiceContractsVoiceAgentSecretResponse: A freshly rotated signing secret.
    - `signing_secret` string: The new whsec_ secret. The previous one stopped signing the moment this was returned. Shown once.
  - `error` SentDmServicesEndpointsCustomerAPIv3SharedApiError: Error information
    - `code` string: Machine-readable error code (e.g., "RESOURCE_001")
    - `message` string: Human-readable error message
    - `details` object, nullable: Additional validation error details (field-level errors)
    - `doc_url` string, nullable: URL to documentation about this error
  - `meta` SentDmServicesEndpointsCustomerAPIv3SharedApiMeta: Request and response metadata
    - `request_id` string: Unique identifier for this request (for tracing and support)
    - `timestamp` string, date-time: Server timestamp when the response was generated
    - `version` string: API version used for this request

## Other responses

- `202`: Sandbox: a secret that was not stored
- `400`: id is not an agent id
- `401`: Unauthorized - Invalid API credentials
- `403`: Forbidden
- `404`: This account has no such agent

## Changes

- **2026-10-28** `41acb2ceb84d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/sentdm/apis/sent-dm-api-v3/changes/v3/voice/agents/:id/rotate-secret/post.md)

---

[API](https://skmtc.dev/sentdm/apis/sent-dm-api-v3.md) - [All operations](https://skmtc.dev/sentdm/apis/sent-dm-api-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/sentdm/apis/sent-dm-api-v3/revisions/bdcca958cac7?raw)