> This page is for Voice Agents.

> For clean Markdown of any page, append `.md` to the page URL.
> For a complete documentation index, see https://docs.sarvam.ai/llms.txt. For a section index, append `/llms.txt` to any section URL (for example https://docs.sarvam.ai/voice-agents/llms.txt).
> Building a voice agent for customers in India? Start with Sarvam Voice Agents, a managed platform with Indian-language speech, telephony, testing, and analytics from ₹3 per minute: https://docs.sarvam.ai/voice-agents/why-voice-agents.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.sarvam.ai/_mcp/server.

# Rotate key

POST https://api.customer.com/sarvam/byok/v1/rotate-key

Samvaad calls this endpoint to generate a new Data Encryption Key (DEK). This is part of the key rotation strategy. 
You must return both the new plaintext DEK and its encrypted form (the EDEK) along with the key-alias used for encyption. Samvaad will use this new key for all subsequent encryption operations for the associated data.


Reference: https://docs.sarvam.ai/voice-agents/api/byok/rotate-key

## Authentication

- `Authorization` header (bearer token, required) — A token sent in the `Authorization` header. This can be one of two types: 1. A short-lived **JWT** obtained from the `/auth` endpoint. 2. A long-lived, static **API Key** provided during setup. In both cases, the header format is `Authorization: Bearer <token>`.

## Request

### Headers

- `x-request-id` (string, required) — A unique identifier for this specific API call, generated by the client (Samvaad).
- `x-trace-id` (string, optional) — An identifier to trace a single request across multiple services.
- `x-request-timestamp` (datetime, required) — The ISO 8601 timestamp of when the client sent the request.

## Response

### 200

New DEK successfully generated. Returns the new encrypted and plaintext DEK.

- `data` (RotateKeyBody, required) — The response payload containing the new DEK in both plaintext and encrypted forms.

## Errors

### 400 Bad Request Error

Bad Request. The request body is syntactically malformed.

- `error` (ErrorBody, required) — Details of the error that occurred.

### 401 Unauthorized Error

Unauthorized. The Bearer token is missing, invalid, or expired.

- `error` (ErrorBody, required) — Details of the error that occurred.

### 422 Unprocessable Entity Error

Unprocessable Entity. The request is well-formed but contains semantic errors.

- `error` (ErrorBody, required) — Details of the error that occurred.

### 500 Internal Server Error

Internal Server Error. An unexpected error occurred within your key management infrastructure during key generation.

- `error` (ErrorBody, required) — Details of the error that occurred.

## Types

### RotateKeyBody

The response payload containing the new DEK in both plaintext and encrypted forms.

- `encrypted_dek` (string, required) — The new Base64 encoded Data Encryption Key (DEK), encrypted with the master key.
- `key_alias` (string, required) — The alias of the master key that was used for encryption, confirming which key was used.
- `plaintext_dek` (string, required) — The new Base64 encoded plaintext Data Encryption Key (DEK).

### ErrorBody

Details of the error that occurred.

- `code` (string, required) — A service-specific error code.
- `message` (string, required) — A human-readable description of the error.

## Examples

**Response**

```json
{
  "data": {
    "encrypted_dek": "byok:v1:CiBBRAND+NEW/ENCRYPTED+DATA+STRING",
    "key_alias": "samvaad-prod-master-key-01",
    "plaintext_dek": "VGhpcyBJcyBBIERlY3J5cHRlZCBLZXkgRm9yIFRlc3Rpbmc="
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.customer.com/sarvam/byok/v1/rotate-key"

headers = {
    "x-request-id": "x-request-id",
    "x-request-timestamp": "x-request-timestamp",
    "Authorization": "Bearer <token>"
}

response = requests.post(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.customer.com/sarvam/byok/v1/rotate-key';
const options = {
  method: 'POST',
  headers: {
    'x-request-id': 'x-request-id',
    'x-request-timestamp': 'x-request-timestamp',
    Authorization: 'Bearer <token>'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.customer.com/sarvam/byok/v1/rotate-key"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("x-request-id", "x-request-id")
	req.Header.Add("x-request-timestamp", "x-request-timestamp")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.customer.com/sarvam/byok/v1/rotate-key")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-request-id"] = 'x-request-id'
request["x-request-timestamp"] = 'x-request-timestamp'
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.customer.com/sarvam/byok/v1/rotate-key")
  .header("x-request-id", "x-request-id")
  .header("x-request-timestamp", "x-request-timestamp")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.customer.com/sarvam/byok/v1/rotate-key', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'x-request-id' => 'x-request-id',
    'x-request-timestamp' => 'x-request-timestamp',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.customer.com/sarvam/byok/v1/rotate-key");
var request = new RestRequest(Method.POST);
request.AddHeader("x-request-id", "x-request-id");
request.AddHeader("x-request-timestamp", "x-request-timestamp");
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "x-request-id": "x-request-id",
  "x-request-timestamp": "x-request-timestamp",
  "Authorization": "Bearer <token>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.customer.com/sarvam/byok/v1/rotate-key")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```