> 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 full documentation content in one file, see https://docs.sarvam.ai/llms-full.txt.
> 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/api-reference/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` (object, required) — 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).

## 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()
```